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 6fb2b70fa5a26d6f15d3a53acc6a5d0f1f650b56..05bbb8564c96a76421a7f3fb82a6b3e2e07512dd 100644 (file)
--- 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 a5df9546f050b493105fcef3af3e8d48578544fa..35d08983e5f6bf387de0996f500da19fc150fd83 100644 (file)
--- 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