OpenSSL Documentation Policy ============================ 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](STYLE.md). This file describes what *must* be documented and where; [STYLE.md](STYLE.md) describes how code comments look. Command line commands and arguments ----------------------------------- 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. Public symbols in the libraries ------------------------------- 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: - guard macros preventing a header file being included twice - new symbols generated automatically via `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](STYLE.md) for the doxygen form. Overviews, conventions, et al ----------------------------- Where additional user-facing information is required, it should be included in the `doc/man7` section. This includes, but is not limited to: - algorithm descriptions and parameters - architectural and subsystem overviews - user guides and tutorials - conventions and reference material (environment variables, glossary, threading rules, file format conventions) Internal functions, structures, globals and macros -------------------------------------------------- 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 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 - upref functions - free functions - simple getter/setter functions - wrappers for other functions (a function that calls a more recent `_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;` File-local items ---------------- 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. Code comments ------------- The form, style, and content guidance for code comments are described in [STYLE.md](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](STYLE.md). Assembly code ------------- 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](STYLE.md). Comments inside the `asm()` body itself use plain C `/* */` comments. There are no *trivial* exceptions for assembly code. Configure options ----------------- New options added to the configuration scripts must be documented in the [INSTALL.md](INSTALL.md) file. Changes and news ---------------- Significant modifications should be documented in the [CHANGES.md](CHANGES.md) file. Very significant features and changes should be documented in the [NEWS.md](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. Automated sanity checking ------------------------- The `make doc-nits` command should be run before submitting a pull request and any problems it locates must be addressed. Language -------- The language used for documentation shall be *British English*. In general the language, abbreviations, layout and formatting should also correspond to the [LDP](https://openssl-library.org/policies/general/glossary/#ldp) guidelines. Common sense ------------ 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](STYLE.md) for the form and content of code comments.