Mind you, the goal of that ongoing work is not to bring LibreSSL
documentation up to OpenBSD documentation quality standards. That
is completely out of the question. It is just not feasible with
any kind of reasonable effort. Such a project might easily consume
a year of work without getting finished.
The short term goal is to make sure that LibreSSL documentation
becomes better than OpenSSL documentation. Not merely better on
average, but better in any conceivable respect. If some particular
detail is documented in OpenSSL, that detail ought to be documented
at least as well in LibreSSL. That is a much, much easier goal to
reach than even coming anywhere near something similar to OpenBSD
quality standards. In fact, we are almost there already, and the
next step after that... - but i'm getting ahead of myself...
The first step i took in getting LibreSSL documentation better than
OpenSSL documentation was ploughing through the version control
history of the OpenSSL documentation - through all of it. That's
about fifteen years of history for about 300 files, roughly 1700
commits, many of them touching multiple files. Excepting those
documentation changes documenting code changes that didn't make it
to LibreSSL (or didn't make it yet), i merged all documentation
improvements to LibreSSL that weren't merged before. However, i did
not merge changes that are not improvements, for example the
indiscriminate deletion of HISTORY and AUTHORS information that
OpenSSL committed, or the silly addition of an inaccurate, identical,
partly misleading, and completely useless COPYRIGHT section to the
displayed text of each and every page. Merging, in this context,
meant merging raw text by hand and manually re-applying markup to
the changed passages, not applying patches, because OpenSSL is still
using the old
perlpod(1) markup language. During the merge, i also
fixed lots of documentation bugs that continue to exist in OpenSSL,
and i improved various of the files in various ways to make them
more readable and conform better to our standard layout and content
While doing this (third) pass through the corpus - the first was
the pod2mdoc conversion, the second jmc@'s copy editing work -,
i also researched the names of all authors who contributed mayor
sections of text to each individual file and added their names,
along with the years in which each file was changed, to each
individual file, sometimes leaving out years that only had trivial
changes or changes that are no longer present in the current version.
I also added the correct license terms to each file. While most
files have the same license, some do have a different one, and since
future files and future major additions will be under our standard
ISC-style OpenBSD license, being clear about the Copyright and
license of each individual file does make sense.
Near the end of this work, i wrote documentation from scratch for
a few dozen functions that were mentioned both in public headers
and in the documentation - in particular in
for horrors - but not actually documented anywhere beyond quoting
the bare prototypes. Right now, i have been working for a few days
on the last two files, X509_dup.pod and d2i_X509.pod. Each of these
lists more than 100 functions. In some cases, the prototypes are
wrong. In almost all cases, the header file specified is wrong,
or none is specified at all. Even though the functions listed there
are all constructors, decoders, and encoders, almost no information
is provided about the purposes or properties of the objects constructed
Yes, even on my quite modern notebook, that NAME section alone
requires scrolling! By now, about half of that is properly documented
Some of the functions listed there are so closely related to functions
documented in other pages that they can be moved to those other
pages. A very small number already simultaneously appeared in the
SYNOPSIS of two pages. But in some other cases, the functions live
in the middle of giant black holes of sizable groups of public
functions with no documentation whatsoever, most notably in the
case of PKCS12. Most functions fall somewhere in the middle,
requiring new pages, some closely, some loosely related to other
existing pages, many on the boundaries of minor or major documentation
gaps. On the whole, X509_dup.pod is a frightful rabbit hole: The
deeper you go down, the more it looks like a dragon's den.
In LibreSSL, working on the documentation is about as difficult as
working on the code in other libraries i'm used to - like libc,
libedit, and the mandoc parsers. So i marvel at the guys who
manage to actually disentangle, flense, and improve that C code!
And by the way, in such an environment, i really need my tools.
In addition to "grep -R"ing both source code trees, i often do
stuff similar to the following:
mandoc -Tlint *.3
doas make install
doas makewhatis /usr/share/man
man -ka 'Ft,Fa,Vt,Va~X509$'
and then use "/", ":t", "t", and "T" searches inside less.
I don't think i could survive in such an environment without
the semantic search facilities provided by the mandoc toolbox.
It will still take at least some days to complete the last two
files, and then we will have reached the goal of making LibreSSL
docs better than OpenSSL docs in each and every respect.
After that, it may make sense to close some of the more gaping
documentation holes in areas of general importance (like BN) and
in areas of current interest (like EC), and to try to bring such
carefully selected areas closer to OpenBSD standards - but even
that may require considerable work, and i'm not yet convinced i
have the time and expertise.
The general problem with OpenSSL documentation is the overwhelming
size of the public user interface. If a user interface is as
ill-designed as the OpenSSL one, with many hundreds of trivial
wrapper functions (the wrapped ones usually also being public!),
many hundreds of macro wrappers, lots of contorted indirection,
sprawling featurism, highly redundant functionality, erratic naming,
and highly dangerous, polymorphic semantics (like: if arg is NULL,
a newly allocated pointer is returned; otherwise, if *arg is NULL,
the newly allocated pointer is assigned to it; otherwise, the object
**arg is reused; if it is empty, FOO, otherwise BAR -- GAAH!)...
I guess i lost track of my sentence, just like you will lose track
of the programming task you are trying to work on when reading such
text in a manual page. Anyway, if an interface is ill-designed to
this extent, it is very hard to document, and even worse, even
high-quality documentation would be bulky, time-consuming to read,
hard to understand due to its complexity, and almost impossible to
follow correctly and safely.
There is a lesson to take away from all this. When implementing
some new functionality, think again before adding anything to the
user interface. If you find no way to avoid enlarging the user
interface, think again, talk to others about it, and think yet
again, until you at least find ways to add *much less* to the user
interface than you originally thought you would have to. Have pity
on the poor guy (hopefully yourself) who will have to document it.
Have even more pity on the (hopefully thousands) of poor users who
will all have to read that documentation in order to use your code.
No effort spent on keeping a user interface concise can ever be
If you are about to add a hundred user interfaces in one go, stop
right there. Just don't do it. NEVER. Even if you tried, you
simply couldn't document it in any quality way. And even if you
could, nobody ought to be willing to read all that. So basically,
nobody will ever be able to use your code properly. At least not
without torturing themselves and spending time they shouldn't.
So once again, just don't do it.
Instead, if you know a bit about cryptography or TLS, consider
helping a bit to polish those turds the mutt has already left behind.
There is plenty of work to do almost everywhere in LibreSSL. Just
compare the <openssl/FOO.h> you care about most to the manual pages,
notice and fill the holes, and help making the text that's already
there readable. Thanks...