1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
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
```
Additionally, public symbols added should contain an entry in the HISTORY
section of their documentation explaining the exact OpenSSL version in which
they have appeared for the first time. The option -i for "find-doc-nits"
can be utilized to check for this. A completely new documentation file
should also contain a HISTORY section with wording along this line, e.g.
"These functions have been added in OpenSSL version xxx.".
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.
|
