Contributed by rueda on from the abandon-all-hope-ye-who-enter-here dept.
Ingo Schwarze (schwarze@) writes in:
You may have noticed that i have been working on LibreSSL documentation for a bit more than a month now. Actually, there already is an undeadly report about the first week of that work:
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 organization.
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 or transcoded:
Yes, even on my quite modern notebook, that NAME section alone requires scrolling! By now, about half of that is properly documented in LibreSSL.
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 wasted.
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...
Thanks very much, Ingo, for the excellent report and extremely brave work!
(Comments are closed)