Commit c17828595f for openssl.org

commit c17828595f60ab0a91c54a8da7c3461387ea77a7
Author: Bob Beck <beck@openssl.org>
Date:   Fri Jun 12 09:55:42 2026 -0600

    Change the Doxygen doc requirement for non public functions

    To be at the prototype site in the internal header file.

    The major reason *Why* we would like to have Doxygen style comments
    describing what internals do is so that they work with modern IDE's
    since most common ones support them.

    It's wonderful to be looking at an internal function, thinking "wtf is this",
    and be able to hover over it and - boink - up comes the docs. This
    typically only works (or works better) when the Doxygen comment is
    at the prototype site, not if it is at the implementation site.

    This also reinforces the requirement that "yes you do this for shared
    functions but you don't need to for statics".

    Reviewed-by: Neil Horman <nhorman@openssl.org>
    Reviewed-by: Milan Broz <mbroz@openssl.org>
    MergeDate: Fri Jul 10 15:37:18 2026
    (Merged from https://github.com/openssl/openssl/pull/29295)

diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md
index 6fb2b70fa5..05bbb8564c 100644
--- a/DOCUMENTATION.md
+++ b/DOCUMENTATION.md
@@ -64,14 +64,22 @@ included in the `doc/man7` section. This includes, but is not limited to:
 Internal functions, structures, globals and macros
 --------------------------------------------------

-Internal functions and macros are those defined in the `include/crypto`
-and `include/internal` directories.
-
-These should all be documented at the point of implementation, using a
-doxygen-style comment block. The comment should describe the purpose
-and, for functions, the input and output arguments and the return
-value. See [STYLE.md](STYLE.md) for the doxygen conventions used by
-OpenSSL.
+Internal functions, structures, globals and macros are non-public
+items declared in any header that is not part of the public API.
+These include items declared in:
+
+- `include/internal/` (shared across subsystems);
+- `include/crypto/` (cryptographic internals);
+- per-directory local headers (for example, `crypto/asn1/asn1_local.h`)
+  shared between source files in a single subdirectory.
+
+These should all be documented at the declaration site -- that is,
+in the header that declares them -- using a doxygen-style comment
+block. For functions, this places the comment at the prototype,
+where editor tooling (clangd and similar) can surface it to readers
+at every call site. The comment should describe the purpose and,
+for functions, the input and output arguments and the return value.
+See [STYLE.md](STYLE.md) for the doxygen conventions used by OpenSSL.

 For *trivial* items, where their operation is obvious from their
 implementation, the documentation requirement is not mandated. The
@@ -96,16 +104,17 @@ obvious. Some representative examples:
 - `struct *next;` in a linked list implementation.
 - `CRYPTO_REF_COUNT refcnt;`

-Static functions and globals and local structures and macros
-------------------------------------------------------------
+File-local items
+----------------

-These are functions, structures, globals and macros local to a specific
-C file or defined for a single directory as part of a local `.h` file.
+These are functions, structures, globals, and macros that are local
+to a single C file: `static` functions, file-scope variables,
+structures, and macros defined inside a `.c` file with no declaration
+in any header.

-These should all be documented at the point of implementation. Follow
-the same rules and exceptions as for internal functions and structures
-above. In some cases slightly more leniency with respect to *trivial*
-can be tolerated.
+These should all be documented at the point of definition. Follow the
+same rules and exceptions as for internal items above. In some cases
+slightly more leniency with respect to *trivial* can be tolerated.

 Code comments
 -------------
diff --git a/STYLE.md b/STYLE.md
index a5df9546f0..35d08983e5 100644
--- a/STYLE.md
+++ b/STYLE.md
@@ -314,10 +314,7 @@ typedef struct foo_st {
  * @param b input integer to add
  * @returns the sum of a and b
  */
-int add(int a, int b)
-{
-    return a + b;
-}
+int add(int a, int b);
 ```

 #### Spec-mirroring variables