Initial Framework for Using Doxygen to Document Public Header Files by m271828 · Pull Request #2908 · aws/aws-lc

m271828 · 2025-12-16T01:44:29Z

Issues:

Resolves P276033715
Resolves P276038464
Addresses P276034041

Description of changes:

Start of moving AWS-LC over to Doxygen for a documentation framework and automatic publication of documentation with each update to main. This creates the initial configuration files, updates the style guide and includes one converted file as an example.

Call-outs:

The documentation itself is not being updated as part of this work, it is being moved to the Doxygen framework. Updating documentation is future work. Doxygen layout has been customized since this is not a C++ project.

Testing:

Doxygen configuration files and symbol linking have been verified correct with local testing, not yet at the stage for testing via GitHub.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license and the ISC license.

codecov-commenter · 2025-12-16T02:22:22Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.09%. Comparing base (43721b5) to head (f66a3bd).
⚠️ Report is 112 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2908      +/-   ##
==========================================
- Coverage   78.10%   78.09%   -0.01%     
==========================================
  Files         682      682              
  Lines      118359   118359              
  Branches    16609    16610       +1     
==========================================
- Hits        92440    92434       -6     
- Misses      25031    25038       +7     
+ Partials      888      887       -1

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

sgmenda

Looking at the failing required test, we might have to regenerate some build files. There's probably a go script or a python script that fixes this. I think this error is coming from /Users/sgmenda/CLionProjects/aws-lc-prs/tests/check_cmake_configure.sh

Adding all changed files to the git tree
+ echo 'Adding all changed files to the git tree'
+ git add -A
+ echo 'Checking for any changes'
+ git diff --exit-code HEAD
Checking for any changes
diff --git a/include/openssl/base.h b/include/openssl/base.h
index b4ac561..98fb568 100644
--- a/include/openssl/base.h
+++ b/include/openssl/base.h
@@ -54,10 +54,7 @@
 #define OPENSSL_HEADER_BASE_H
 
 
-/**
- * @file
- * @brief This file should be the first included by all AWS-LC headers.
- */
+// This file should be the first included by all BoringSSL headers.
 
 #include <stddef.h>
 #include <stdint.h>
@@ -423,12 +420,6 @@ typedef struct evp_aead_st EVP_AEAD;
 typedef struct evp_aead_ctx_st EVP_AEAD_CTX;
 typedef struct evp_cipher_ctx_st EVP_CIPHER_CTX;
 typedef struct evp_cipher_st EVP_CIPHER;
-
-/**
- * @typedef EVP_ENCODE_CTX
- * @copydoc evp_encode_ctx_st
- * @see evp_encode_ctx_st
- */

docs/api/Doxyfile

STYLE.md

m271828 · 2026-01-24T00:02:03Z

This is what it looks like when hosted locally.

m271828 · 2026-01-24T00:40:23Z

Looking at the failing required test, we might have to regenerate some build files. There's probably a go script or a python script that fixes this. I think this error is coming from /Users/sgmenda/CLionProjects/aws-lc-prs/tests/check_cmake_configure.sh

Adding all changed files to the git tree
+ echo 'Adding all changed files to the git tree'
+ git add -A
+ echo 'Checking for any changes'
+ git diff --exit-code HEAD
Checking for any changes
diff --git a/include/openssl/base.h b/include/openssl/base.h
index b4ac561..98fb568 100644
--- a/include/openssl/base.h
+++ b/include/openssl/base.h
@@ -54,10 +54,7 @@
 #define OPENSSL_HEADER_BASE_H
 
 
-/**
- * @file
- * @brief This file should be the first included by all AWS-LC headers.
- */
+// This file should be the first included by all BoringSSL headers.
 
 #include <stddef.h>
 #include <stdint.h>
@@ -423,12 +420,6 @@ typedef struct evp_aead_st EVP_AEAD;
 typedef struct evp_aead_ctx_st EVP_AEAD_CTX;
 typedef struct evp_cipher_ctx_st EVP_CIPHER_CTX;
 typedef struct evp_cipher_st EVP_CIPHER;
-
-/**
- * @typedef EVP_ENCODE_CTX
- * @copydoc evp_encode_ctx_st
- * @see evp_encode_ctx_st
- */

Fixed. base.h is generated by base.h.in looking at our CMake files. A diff between the two files is done as a sanity check. I only made the changes in base.h. Adding them in base.h.in fixes the issue.

@sgmenda

### Description of changes: * Bump urllib3 from 2.6.0 to 2.6.3 in /tests/ci by @dependabot[bot] in #2932 * Add weekly automated check for outdated third-party test vectors by @sgmenda in #2933 * Enable Hybrid PQ KeyShares by default by @alexw91 in #2531 * Remove AVX conditional from cmake script by @torben-hansen in #2958 * openssl-ca command implementation for self-sign certificates by @skmcgrail in #2937 * Initial Framework for Using Doxygen to Document Public Header Files by @m271828 in #2908 * Move md4 out of FIPS module by @torben-hansen in #2956 * Fix image-build-windows workflow to only push on workflow_call and workflow_dispatch by @skmcgrail in #2961 * Remove FIPS counter framework and other tidying up by @torben-hansen in #2947 * Model Device Farm CI Resources in CDK by @skmcgrail in #2965 * Adds a new randomness generation API by @torben-hansen in #2963 * Migrate Android Testing to GitHub Actions by @skmcgrail in #2969 * Ensure pkcs7 checks ASN1_TYPE->type by @skmcgrail in #2968 * Fix checkout logic for android-omnibus by @skmcgrail in #2970 * Add missing env vars to check-vectors workflow step by @sgmenda in #2962 * Shorten Windows Build Directory Path by @skmcgrail in #2974 * Bump mysql cluster version by @WillChilds-Klein in #2967 * Integrate Wycheproof ML-DSA test vectors by @sgmenda in #2973 * Simplify FIPS conditional in top-level build script by @torben-hansen in #2976 * Fix aws-lc-rs CI job by @justsmth in #2966 * Add method to get type of ML-DSA instance configured under EVP PKEY by @torben-hansen in #2980 * Nmap build needs liblinear by @justsmth in #2985 * Disable SLP vectorizer for FIPS shared library builds on GCC 14+ by @geedo0 in #2977 * Update Wycheproof ECDSA test vectors and fix workflow typo by @sgmenda in #2972 * Address some CMake findings by @skmcgrail in #2979 * Bump bytes from 1.7.1 to 1.11.1 in /tests/ci/lambda by @dependabot[bot] in #2983 * Support GCC 4.8 for aarch64 by @justsmth in #2964 * Free potential memory before assigning new pointer by @torben-hansen in #2989 * Add PyOpenSSL integration test by @WillChilds-Klein in #2992 * Ensure index argument is not negative in ASN1_BIT_STRING_set_bit by @torben-hansen in #2987 * Ensure no overflow in signed output length in do_buf by @torben-hansen in #2988 * Remove redundant CPython 3.9 integration test by @WillChilds-Klein in #2996 * Ensure public key is set before verifying through ML-DSA verify by @torben-hansen in #2990 * Correct CCM nids in object definition by @torben-hansen in #2991 * Address Reported Bug Findings by @skmcgrail in #3000 * Fix CI: gcc-4.8 by @justsmth in #3011 * Fix Windows CI: use `cd /d` in run_windows_tests.bat to handle cross-drive paths by @justsmth in #3012 * Fix OPENSSL_memchr per C23 by @justsmth in #3008 * Fix argument order in `hmac_copy` by @justsmth in #3014 * Miscellaneous CI improvements by @skmcgrail in #2978 * Fix CI: mariadb by @justsmth in #3015 * Update Ubuntu 24:04 image compiler verification by @skmcgrail in #3017 * Support WASM/Emscripten by @justsmth in #2959 * Generate Rust Bindings by @justsmth in #2999 By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license and the ISC license.

Finish style guide.

1ad4778

m271828 requested a review from a team as a code owner December 16, 2025 01:44

m271828 added 6 commits December 15, 2025 23:04

Make base64.h final example

ed10c5d

Merge branch 'main' into doxygen-base

fa89b6f

Add typedef doc in base.h

54cc4db

Add file doc

bad19f5

Merge branch 'main' into doxygen-base

5f3ec85

Merge branch 'main' into doxygen-base

e69bb46

sgmenda requested changes Jan 23, 2026

View reviewed changes

sgmenda reviewed Jan 23, 2026

View reviewed changes

docs/api/Doxyfile Show resolved Hide resolved

STYLE.md Show resolved Hide resolved

Update base.h.in

f66a3bd

m271828 requested a review from sgmenda January 24, 2026 00:40

skmcgrail approved these changes Jan 24, 2026

View reviewed changes

sgmenda approved these changes Jan 24, 2026

View reviewed changes

sgmenda merged commit 11de26d into aws:main Jan 24, 2026
399 of 400 checks passed

justsmth mentioned this pull request Feb 20, 2026

Prepare v1.68.0 #3022

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Initial Framework for Using Doxygen to Document Public Header Files#2908

Initial Framework for Using Doxygen to Document Public Header Files#2908
sgmenda merged 8 commits intoaws:mainfrom
m271828:doxygen-base

m271828 commented Dec 16, 2025

Uh oh!

codecov-commenter commented Dec 16, 2025 •

edited

Loading

Uh oh!

sgmenda left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

m271828 commented Jan 24, 2026

Uh oh!

m271828 commented Jan 24, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

m271828 commented Dec 16, 2025

Issues:

Description of changes:

Call-outs:

Testing:

Uh oh!

codecov-commenter commented Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

sgmenda left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

m271828 commented Jan 24, 2026

Uh oh!

m271828 commented Jan 24, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

codecov-commenter commented Dec 16, 2025 •

edited

Loading

sgmenda left a comment •

edited

Loading