mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-04-24 20:51:14 +08:00
Code Issues Packages Projects Releases Wiki Activity

doc: add HOWTO document about Documenting public Functions and Macros

Browse Source 
Co-authored-by: Matthias St. Pierre <matthias.st.pierre@ncp-e.com>
Co-authored-by: Tomáš Mráz <tm@t8m.info>
Co-authored-by: Lin2Jing4 <35728132+Lin2Jing4@users.noreply.github.com>
Co-authored-by: Richard Levitte <levitte@openssl.org>

Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: David von Oheimb <david.von.oheimb@siemens.com>
Reviewed-by: Tim Hudson <tjh@openssl.org>
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/17926)
This commit is contained in:
Michael Richardson 2022-03-19 09:11:06 -04:00 committed by Tomas Mraz
parent 30ab774770
commit c3637cafd3
1 changed files with 176 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

176
doc/HOWTO/documenting-functions-and-macros.md Normal file
View File

@ -0,0 +1,176 @@
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.
[documentation-policy]: https://www.openssl.org/policies/technical/documentation-policy.html
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 BIO_set_dgram_origin(3) undocumented
include/openssl/bio.h: macro BIO_get_dgram_origin(3) undocumented
include/openssl/bio.h: macro BIO_set_dgram_dest(3) undocumented
include/openssl/bio.h: macro BIO_get_dgram_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/BIO_set_dgram_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 generate_doc_buildinfo
```
this will update `doc/build.info`.
You should git add the result as `generate_doc_buildinfo` 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
BIO_get_dgram_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 `BIO_set_dgram_foo()`
and a public function-like macro `BIO_set_dgram_bar()`:
```diff
diff --git a/crypto/bio/bss_dgram.c b/crypto/bio/bss_dgram.c
index 82d382cf4e..30382f0abe 100644
--- a/crypto/bio/bss_dgram.c
+++ b/crypto/bio/bss_dgram.c
@@ -192,6 +192,13 @@ BIO *BIO_new_dgram(int fd, int close_flag)
return ret;
}
+
+int BIO_set_dgram_foo(BIO* b, int foo)
+{
+ return foo;
+}
+
+
static int dgram_new(BIO *bi)
{
bio_dgram_data *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 bio_dgram_sctp_prinfo {
#define BIO_set_dgram_dest(b, addr) BIO_ctrl(b, BIO_CTRL_DGRAM_SET_PEER, 0, addr)
#define BIO_get_dgram_dest(b, addr) BIO_ctrl(b, BIO_CTRL_DGRAM_GET_PEER, 0, addr)
+int BIO_set_dgram_foo(BIO* b, int foo);
+#define BIO_set_dgram_bar(b, bar) BIO_ctrl(b, BIO_CTRL_DGRAM_SET_ADDR, 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 BIO_set_dgram_bar(3) undocumented
# 1 macros undocumented (count is approximate)
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.
[module definition file]: https://docs.microsoft.com/en-us/cpp/build/exporting-from-a-dll-using-def-files
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 @@ BN_signed_bn2native ? 3_1_0 EXIST::FUNCTION:
ASYNC_set_mem_functions ? 3_1_0 EXIST::FUNCTION:
ASYNC_get_mem_functions ? 3_1_0 EXIST::FUNCTION:
BIO_ADDR_dup ? 3_1_0 EXIST::FUNCTION:SOCK
+BIO_set_dgram_foo ? 3_1_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 BIO_set_dgram_foo(3) undocumented
# 1 libcrypto names are not documented
include/openssl/bio.h: macro BIO_set_dgram_bar(3) undocumented
# 1 macros undocumented (count is approximate)
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.