This document describes the code documentation and commenting requirements for the OpenSSL project.
The project's documentation is about making the libraries and tools more accessible to our users and making the code more maintainable. This policy applies to new submissions; existing code does not uniformly conform to it and will be brought up to standard gradually.
Any non-trivial change to existing code must bring the affected code into conformance with this policy as part of the same change. In particular, renaming or relocating functions, changes to public APIs, and any change that would render an existing POD page or in-source comment inaccurate require the corresponding documentation to be updated. This includes adding documentation that was previously absent where the change brings the affected code within the scope of this policy.
The form and style of code comments themselves -- comment markers, layout, the use of /** and /*- blocks, doxygen markup, the structure of the sample multi-line comment, and similar -- are described in STYLE.md. This file describes what must be documented and where; STYLE.md describes how code comments look.
All new commands, as well as new or modified arguments to existing commands, must be documented in the doc/man1 directory. This documentation is in POD format.
All new public symbols must be documented in a POD manual page in the doc/man3 directory. This includes types, macros, and functions.
The allowed exceptions are:
make update (errors, objects, etc.)Each public function‘s declaration in its public header must carry a doxygen comment block. The block’s @see must include the function's own manual page (name(3)) and may include additional manual pages that a caller needs to use the function correctly. The doxygen block is a navigation aid pointing to the canonical reference documentation in the corresponding POD file; see STYLE.md for the doxygen form.
Where additional user-facing information is required, it should be included in the doc/man7 section. This includes, but is not limited to:
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);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 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 following are generally representative of trivial items, however it is quite possible for any of these to be non-trivial in specific instances and therefore require documentation:
OSSL_DISPATCH tables_ex variant or a group of functions that call a common internal routine)For structures, each of the fields should be commented stating its purpose. Again, a trivial exception applies where the purpose is obvious. Some representative examples:
OSSL_LIB_CTX *ctx; where there is only one library context referenced in the structure.struct *next; in a linked list implementation.CRYPTO_REF_COUNT refcnt;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 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.
The form, style, and content guidance for code comments are described in STYLE.md. Comments are required at the points described in the internal and static sections above, subject to the trivial exception, and at the additional points described in STYLE.md.
Assembly code should include a good description of the algorithm and approach being used. This should be followed by a performance comparison and then the assembly code itself. The assembly code should be well commented, but it is not necessary to comment every line. A comment describing each block of code suffices.
For pure-assembly modules (.s files and the perlasm scripts that generate them), comments use the native syntax of the assembler or generator (typically #). Doxygen-style markup does not apply here; the algorithm description, performance comparison, and per-block comments described above are still required.
For assembly that appears inline inside a C file (within an asm() statement, for example), the surrounding C function is documented with doxygen-style C comments as for any other C code; see STYLE.md. Comments inside the asm() body itself use plain C /* */ comments.
There are no trivial exceptions for assembly code.
New options added to the configuration scripts must be documented in the INSTALL.md file.
Significant modifications should be documented in the CHANGES.md file.
Very significant features and changes should be documented in the NEWS.md file.
In both cases, the added note should be short and to the point, and should be written for users of the library, focusing on impact rather than implementation details.
The make doc-nits command should be run before submitting a pull request and any problems it locates must be addressed.
The language used for documentation shall be British English.
In general the language, abbreviations, layout and formatting should also correspond to the LDP guidelines.
Comments and documentation are to improve readability and comprehension. Where the code is obvious, there is no need to include a comment. However, common sense applies: always err in favour of including more comments than less or none. Code that you have just written that is obvious will not necessarily be to someone else two years later. See STYLE.md for the form and content of code comments.