@jericson I say those are just lame excuses. OpenSSL has soon existed for *thirty* years and there's clearly still no serious attempt to even try to do good documentation. Lots of the function calls even remain the same so there has been some time to do something.

I honestly cannot understand how a thriving project can claim to be for users and at the same time ignore their docs to this degree.

But that's just my personal opinion.

They can only be lame excuses if they were excuses. I agree with you that documentation needs help. It's something that came up time and again in our survey in June. And, of course, I've consulted the documentation myself to try to understand the library. It's a problem.

You know the history of OpenSSL better than I do. Nothing anyone can do about the past. The question is how do we fix the situation? My answer is that we probably need a technical writer who knows how to structure useful documentation.

In my experience, documentation doesn't come naturally. Everyone wants it, but few people want to write it. (You can kinda see that in the OpenSSL forks which don't seem to be much interested in improving the documentation either.) You are absolutely correct that user-oriented projects make documentation a priority.

To go back to your initial post, is this issue related? "Horrible d2i_TYPE*() reuse behavior leads to crashes on error" sounds pretty similar to what you are describing.

(I disagree with the idea that undocumented functions are worse than functions with "a few lines of docs", by the way. Better to have an obvious problem than paper over it.)

Horrible `d2i_TYPE*()` reuse behavior leads to crashes on error, e.g., for `ASN1_item_sign_ctx()`

d2i_X509_ALGOR() etc. behave badly as explained in doc/man3/d2i_X509.pod: In some versions of OpenSSL the "reuse" behaviour of d2i_TYPE() when *a is valid is broken and some parts of the reused str...

^{DDvO (GitHub)}