This is true, but often the code does not match the docs. Or, the docs leave something out (is this dynamically allocated? Who is responsible for deallocating it, etc).
Reconciling what the code does vs. what it should do vs. what is ambiguous is always a matter for debate (is that a feature or a bug?), but when you don't have the code and you do have docs only, there will always be something missing in the docs, whether a bug or ambiguity. So, pick your poison: docs that do not completely describe the code you don't have, or code that doesn't do what you think it does. The first you pay for, the second you don't, though you can pay someone who might understand it better. The bottom line is this: if you want better docs for free code, PAY to have then written, or shut up. Maybe someday someone will, altruistically, document the combined wisdom here and in the code. But no one owes it to anyone. -----Original Message----- From: owner-openssl-us...@openssl.org [mailto:owner-openssl-us...@openssl.org] On Behalf Of Tim Ward Sent: Wednesday, November 25, 2009 12:59 AM To: openssl-users@openssl.org Subject: Re: General question about documentation From: "Graham Leggett" <minf...@sharp.fm> > > Use the source: while not the easiest to read it is the most accurate > documentation available at any given time. (No, this is not a > justification for a lack of or bad documentation). The objection, and it's a major one, to reverse engineering the API from the source is that the source doesn't tell you what the contract is - it doesn't tell you what this API guarantees to deliver, it only tells you what the current version's implementation actually does. So if you rely on the implementation of the current version your code will break when the next version does something different, which is not the case if you're writing to a published and documented API as you won't be accidentally relying on non-guaranteed implementation details. Tim Ward - Brett Ward Limited - 07801 703 600 www.brettward.co.uk ______________________________________________________________________ OpenSSL Project http://www.openssl.org User Support Mailing List openssl-users@openssl.org Automated List Manager majord...@openssl.org ______________________________________________________________________ OpenSSL Project http://www.openssl.org User Support Mailing List openssl-users@openssl.org Automated List Manager majord...@openssl.org
