That works for *future* documentation for *new* code, but it doesn't address the existing gaps.
Perhaps examining where the existing gaps are biggest would be productive.
For me, two areas have always been confusing:
1) What objects are dynamically allocated, appropriately reference counted, and
have associated pointer destructors intended to be use on every reference no
longer needed? IOW, If I get an X509_FOO*, should I ALWAYS call X509_FOO_free
on it, for ALL FOOs?
2) Things like OCSP, CRLs, and other SSL "extensions" have always stumped me.
Is it something the user of the library is responsible for, when validating a
cert, or can the library do it itself when I try to establish an SSL
connection, and to what degree can I control this? It always struck me that the
cert validation callback is the place to do this, but I take heed of the fact
that openssl is supposed to have a reasonable default cert validation routine
and not to replace it without good reason.
3) Better documentation regarding BIO chaining and BIOs in general. BIOs are
"cool", they remind me a bit of System V Streams.
In general, I've seen good docs regarding the "trees" of individual functions,
fair docs regarding type name and function patterns (e.g. regarding ASN1 to
internal conversion), and poor docs of the various "forests" of types of
functions and their interaction (CRL support, OCSP support, TLS1 Hello
extensions, etc.)
-----Original Message-----
From: owner-openssl-us...@openssl.org on behalf of Victor Duchovni
Sent: Wed 12/2/2009 11:29 AM
To: openssl-users@openssl.org
Subject: Re: General question about documentation
On Wed, Dec 02, 2009 at 11:17:44AM -0800, Rene Hollan wrote:
>
> To someone who uses code, it doesn't matter a fig what the designer was
> thinking. It matter what the code does. Then you can decide if it does
> something correctly enough to be usable in the state it's in.
>
My sense is that this thread is no longer productive. Perhaps we can stop.
FWIW, the Postfix project strives to avoid documentation gaps, by not
accepting code contributions that are not *fully* documented at the time
the code is contributed. The first step towards improving OpenSSL docs,
would be to raise the bar for contributed code, and on-going development.
If code is not documented, it should not move from dev branches to the
trunk, and definitely not from the trunk to release branches.
Once on-going documentation stops being optional, one can start thinking
about past sins.
I don't want to add fuel to the fire, this is my final comment in this
thread. Sorry to prolong it any further...
--
Viktor.
______________________________________________________________________
OpenSSL Project http://www.openssl.org
User Support Mailing List openssl-users@openssl.org
Automated List Manager majord...@openssl.org
<<winmail.dat>>
