Add Doxygen documentation for missing API functions

[devin-ai-integration]

Description

This PR adds comprehensive Doxygen documentation for 2239 previously undocumented public API functions across 52 header files in the wolfSSL project. The documentation follows the existing wolfSSL Doxygen format and conventions.

Scope of Changes

All changes are documentation-only additions to files in doc/dox_comments/header_files/. No functional code was modified.

Files documented (52 total):

• Cryptographic primitives: aes.h, arc4.h, ascon.h, camellia.h, chacha.h, chacha20_poly1305.h, des3.h, idea.h, rabbit.h, rc2.h
• Hash functions: md2.h, md4.h, md5.h, sha.h, sha256.h, sha3.h, sha512.h, ripemd.h, hash.h
• MACs: hmac.h, cmac.h, poly1305.h
• Public key crypto: rsa.h, ecc.h, dh.h, dsa.h, ed25519.h, ed448.h, curve25519.h, curve448.h
• ASN.1/X.509: asn.h, asn_public.h
• PKI: ocsp.h, pkcs7.h, pkcs11.h, pkcs12.h, pem.h
• TLS/SSL: ssl.h (72 newly documented functions including ECH, SRTP, multicast, session management, and more)
• Utilities: random.h, pwdbased.h, signature.h, compress.h, error-crypt.h, logging.h, types.h, wc_encrypt.h, wc_port.h, wolfio.h, srp.h

Documentation Format

Each function includes:

• \ingroup tag for categorization
• \brief description (wrapped at 80 characters)
• \return statements for all possible return values
• \param descriptions for each parameter
• _Example_ section with realistic usage code (where applicable)
• \sa cross-references to related functions

Key Statistics

• Total commits: 108 documentation commits
• Lines added: ~23,423 lines to ssl.h alone, plus thousands more across other files
• Functions documented: 2239 functions across 52 header files
• Branch: devin/1763748386-add-missing-api-docs

Link to Devin run: https://app.devin.ai/sessions/09417bcfdab948d6afcd5012e2c7597c
Requested by: andrew@wolfssl.com

Testing

Documentation generation was attempted using doc/generate_documentation.sh -html but encountered environment issues (missing doxygen tool). The documentation follows existing patterns and conventions found in the codebase.

Manual verification performed:

• All documentation follows existing Doxygen format
• 80-character line limit maintained throughout
• Parameter names match function signatures
• Return value descriptions included
• Usage examples use relative paths (no absolute machine-specific paths)
• Cross-references point to related functions

Checklist

• added tests - N/A (documentation only)
• updated/added doxygen - Yes, this is the entire purpose of the PR
• updated appropriate READMEs - N/A (documentation only)
• Updated manual and documentation - Yes, via Doxygen comments

Review Focus Areas

Given the large scale of this PR (2239 functions documented), reviewers should focus on:

1. Format consistency: Verify a sample of functions follow the existing Doxygen conventions
2. Line length: Spot-check that lines don't exceed 80 characters
3. Parameter accuracy: Verify parameter descriptions match function signatures
4. Return value accuracy: Check that return value descriptions are correct
5. Example code: Review example code blocks for syntax and correctness
6. Cross-references: Verify \sa tags point to valid related functions
7. Group tags: Check that \ingroup tags are appropriate for each function

Note: Due to the volume of changes, it may be practical to review a representative sample from each header file rather than every single function. The documentation was generated systematically following the same patterns throughout.

Potential risks:

• Documentation accuracy: Descriptions were inferred from function signatures and may need technical review
• Example code: Usage examples weren't compiled/tested and may contain errors
• Completeness: Some edge cases or special behaviors may not be fully documented

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[wolfSSL-Bot]

Can one of the admins verify this patch?

[dgarske]

Compatibility API docs need to be in separate doxy files. And one can argue they shouldn’t be here in wolfSSL at all and to see the OpenSSL documentation

[devin-ai-integration]

Thank you for the feedback! I want to clarify the desired approach for OpenSSL compatibility API documentation before making changes.

Scope Identified

I've documented approximately 774 OpenSSL compatibility API functions across the files (about 34.5% of the 2239 total):

• aes.h: 9 wolfSSL_AES_* functions (AES compatibility layer)
• evp.h: 212 EVP_* functions (almost the entire file)
• ssl.h: 432 BIO_*, X509_*, ASN1_*, PKCS* functions
• pem.h: ~32 PEM_* functions (likely compatibility)

Questions for Guidance

1. Remove or Move?

   • Should I remove OpenSSL compatibility API docs entirely and defer to OpenSSL documentation?
   • Or move them into separate Doxygen files with a dedicated group?

2. If Moving:

   • What directory and naming convention should I use? (e.g., doc/dox_comments/compat/openssl_aes.h)
   • What \ingroup tag should they use? (e.g., OpenSSLCompat)
   • Does the Doxygen generator already include a compat directory, or should I keep files under header_files/ with a different naming pattern?

3. Documentation Style:

   • Are minimal stubs acceptable (e.g., "Compatibility layer for OpenSSL's AES_set_encrypt_key. See OpenSSL documentation.")?
   • Or would you prefer short wolfSSL-specific notes highlighting differences and caveats?

4. Scope:

   • Should I apply the same treatment to all compatibility APIs (EVP, BIO, X509, PEM, etc.)?

5. Pilot Approach:

   • Would it be helpful if I start by moving just the 9 AES compatibility functions as a small test case to align on structure and grouping before proceeding with the larger sets?

I'm happy to implement whichever approach the project prefers. Please let me know your preference and I'll proceed accordingly.