Project: Pipy (Orchestration & Management / Service Proxy)
File: documenting-functions-and-macros.md

Documenting public Functions and Macros ======================================= In the last few years, the OpenSSL project has strived to improve the quality and coverage of the API documentation. A while ago, this goal has been turned into an official [documentation-policy]. This policy is actively enforced by the `make doc-nits` target resp. `check-docs` GitHub action. If you add a new public function or macro to a header file without documenting it, it will give you an error message like this: ```text include/openssl/bio.h: macro BIOsetdgram_origin(3) undocumented include/openssl/bio.h: macro BIOgetdgram_origin(3) undocumented include/openssl/bio.h: macro BIOsetdgram_dest(3) undocumented include/openssl/bio.h: macro BIOgetdgram_dest(3) undocumented ``` and you'll want to document this. So, create a new `.pod` file named `doc/man3/FUNCTION.pod`. If you are asked to document several related functions in that file, you can create a single pod file in which you document them together. In this case, use the name of the first function as the file name, like for the above example: ```text doc/man3/BIOsetdgram_origin.pod ``` If you do use an unrelated name (like `BIO_dgram.pod`) then you'll get a warning about that. Next, you need to add your new file to the `doc/build.info` file. This command does it automatically for you: ```console $ make generatedocbuildinfo ``` this will update `doc/build.info`. You should git add the result as `generatedocbuildinfo` is not run on every build. With these two changes, running `make doc-nits` locally should now agree with you that you have documented all your new defines, but it might then complain: ```text BIOgetdgram_dest(3) is supposedly internal (maybe missing from other.syms) but is documented as public ``` If it is the case that your interface is meant to be public, then you need to edit the file `util/other.syms` to add the names of your `#define` functions. This file gets sorted alphabetically prior to each major release, but new additions should be placed at the end of the file. Example For demonstration purposes, two new public symbols have been added by "implementing" a public function `BIOsetdgram_foo()` and a public function-like macro `BIOsetdgram_bar()`: ```diff diff --git a/crypto/bio/bssdgram.c b/crypto/bio/bssdgram.c index 82d382cf4e..30382f0abe 100644 a/crypto/bio/bss_dgram.c +++

@@ -192,6 +192,13 @@ BIO *BIOnewdgram(int fd, int close_flag) return ret; } +int BIOsetdgram_foo(BIO* b, int foo) +{ return foo; +} static int dgram_new(BIO *bi) { biodgramdata data = OPENSSL_zalloc(sizeof(data)); diff --git a/include/openssl/bio.h.in b/include/openssl/bio.h.in index c70185db34..4ddea2f96b 100644 a/include/openssl/bio.h.in +++ b/include/openssl/bio.h.in @@ -485,6 +485,9 @@ struct biodgramsctp_prinfo { +int BIOsetdgram_foo(BIO* b, int foo); +#define BIOsetdgrambar(b, bar) BIOctrl(b, BIOCTRLDGRAMSETADDR, 0, bar) /* name is cast to lose const, but might be better to route through a function so we can do it safely ``` If you run `make doc-nits`, you might be surprised that it only complains about the undocumented macro, not the function: ```console $ make doc-nits /usr/bin/perl ./util/find-doc-nits -c -n -l -e include/openssl/bio.h: macro BIOsetdgram_bar(3) undocumented make: * [Makefile:3833: doc-nits] Error 1 ``` The explanation for this is that one important step is still missing, it needs to be done first: you need to run ```console $ make update ``` which triggers a scan of the public headers for new API functions. All new functions will be added to either `util/libcrypto.num` or `util/libssl.num`. Those files store the information about the symbols which need to be exported from the shared library resp. DLL. Among other stuff, they contain the ordinal numbers for the [module definition file] of the Windows DLL, which is the reason for the `.num` extension. After running `make update`, you can use `git diff` to check the outcome: ```diff diff --git a/util/libcrypto.num b/util/libcrypto.num index 394f454732..fc3c67313a 100644 a/util/libcrypto.num +++ b/util/libcrypto.num @@ -5437,3 +5437,4 @@ BNsignedbn2native ? 310 EXIST::FUNCTION: ASYNCsetmemfunctions ? 31_0 EXIST::FUNCTION: ASYNCgetmemfunctions ? 31_0 EXIST::FUNCTION: BIOADDRdup ? 310 EXIST::FUNCTION:SOCK +BIOsetdgramfoo ? 31_0 EXIST::FUNCTION: ``` The changes need to be committed, ideally as a separate commit: ```console $ git commit -a -m "make update" ``` which has the advantage that it can easily be discarded when it becomes necessary to rerun `make update`. Finally, we reached the point where `make doc-nits` complains about both symbols: ```console $ make doc-nits /usr/bin/perl ./util/find-doc-nits -c -n -l -e crypto: function BIOsetdgram_foo(3) undocumented include/openssl/bio.h: macro BIOsetdgram_bar(3) undocumented make: * [Makefile:3833: doc-nits] Error 1 ``` Summary The bottom line is that only the way how the public symbols are recorded is different between functions and macros, the rest of the documentation procedure is analogous.