Not quite. The docs may not indicate whether a returned reference is dynamically allocated, statically allocated, reference counted, how to deallocate, etc. The API will still be correct as far as a reference being returned, but the documentation will be incomplete.
Often the library implementer has to make a design decision to fill a gap that the documentation leaves. It is therefore possible for the documentation to correctly describe the API, but not to a sufficient degree of completeness for other code to use it correctly and effectively. Having the code lets one determine WHAT IT DOES, unambiguously. It may be possible to use it in that state to do what YOU WANT, or it may have an implementation error. But it can't have an implementation error if the documentation does not cover that detail. Correct documentation is not enough. Complete documentation is necessary, but often an unrealistic goal, especially when code is still in flux (and library implementation details that affect library use have not been firmed up). Do you prefer incomplete but correct documentation, or complete but possibly incorrect documentation? Most open source projects strive for correctness over completeness -- likely because the missing bits can be determined through review of the code as to those aspects without having to review it completely to reverse engineer any docs. Then there is the issue of the code following an RFC but the docs not matching it. Should the code follow the standard or the docs? Which is wrong? (My bet is on the docs). The BIGGEST issue I have with openssl is when I get a pointer to some subordinate piece of information managed by, say, an X509_foo. I call some function taking an X509_foo* and get an X509_bar*. O.K. What do I do with that X509_bar* when I no longer need it? X509_bar_free it? Dunno -- maybe it isn't reference counted and it's lifetime is bounded by the lifetime of X509_foo, and all I need to do is lose my pointer to it (let it go out of function scope when the function returns). If I X509_bar_free it, and it isn't reference counted, or actually part of the internals of the X509_foo object, I've done a bad thing. Here I see the docs as lacking a description of the GLOBAL approach to dynamically allocated objects, while I do see local hints about some of them. Reading code is not has hard as some think -- you eventually get the idea of "what s/he was thinking". That's not to say it's easy for everyone. But it sure beats following docs and finding things don't work because the docs don't cover some aspect one was forced to assume and was implemented differently. -----Original Message----- From: owner-openssl-us...@openssl.org on behalf of Mark H. Wood Sent: Wed 12/2/2009 6:47 AM To: openssl-users@openssl.org Subject: Re: General question about documentation On Tue, Dec 01, 2009 at 03:23:15PM -0800, Rene Hollan wrote: > The problem is that the documentation may not be correct, sending your coders > on a wild goose chase. Bah, if the code does not do what the documentation describes then the *code* is incorrect. Documentation can only be incorrect if it does not model the problem that the code is intended to solve. -- Mark H. Wood, Lead System Programmer mw...@iupui.edu Friends don't let friends publish revisable-form documents.
