[prev in list] [next in list] [prev in thread] [next in thread]
List: openssl-users
Subject: Re: General question about documentation
From: Kenneth Goldman <kgoldman () us ! ibm ! com>
Date: 2009-11-30 15:34:39
Message-ID: OFA7C25124.5AF3DA9B-ON8525767E.0054124C-8525767E.0055925D () us ! ibm ! com
[Download RAW message or body]
owner-openssl-users@openssl.org wrote on 11/26/2009 06:35:42 PM:
> > Finally, the source code IS the only reliable source of documentation
> > (assuming you can trust your compiler, OS, and hardware to do "the
> > right thing"). It isn't the most CONVENIENT, which is why we desire
> > other forms.
Two problems:
1 - Reading the source is only as reliable as the skill of the reader and
the comments in the code. I'd rather have the answers than a research
project.
2 - If I read the source, I can't determine which functions are stable
and intended to be used by applications and which are internal and
subject to change or deletion with every release.
> the implementation details of the 250-odd API entry points in libssl.so
> would tell me very little about how to properly USE those APIs, and in
> fact, designing an application around my interpretation of the library
> developers intent would likely lead me down some rabbit holes I'd rather
> not explore.
User manual type documentation would be nice, but I'd be content with
a more complete implementation of what's there now. E.g., the AES
functions are not documented yet.
I find the current documentation quite clear and easy to use. My
only issue is that some functions are just not documented.
[Attachment #3 (text/html)]
<html><body>
<p><tt>owner-openssl-users@openssl.org wrote on 11/26/2009 06:35:42 PM:<br>
</tt><br>
<tt>> > Finally, the source code IS the only reliable source of documentation <br>
> > (assuming you can trust your compiler, OS, and hardware to do "the <br>
> > right thing"). It isn't the most CONVENIENT, which is why we desire <br>
> > other forms.<br>
</tt><br>
<tt>Two problems:</tt><br>
<br>
<tt>1 - Reading the source is only as reliable as the skill of the reader and</tt><br>
<tt>the comments in the code. I'd rather have the answers than a research</tt><br>
<tt>project.</tt><br>
<br>
<tt>2 - If I read the source, I can't determine which functions are stable</tt><br>
<tt>and intended to be used by applications and which are internal and</tt><br>
<tt>subject to change or deletion with every release.</tt><br>
<br>
<tt>> the implementation details of the 250-odd API entry points in libssl.so <br>
> would tell me very little about how to properly USE those APIs, and in <br>
> fact, designing an application around my interpretation of the library <br>
> developers intent would likely lead me down some rabbit holes I'd rather <br>
> not explore.<br>
</tt><br>
<tt>User manual type documentation would be nice, but I'd be content with</tt><br>
<tt>a more complete implementation of what's there now. E.g., the AES</tt><br>
<tt>functions are not documented yet.</tt><br>
<br>
<tt>I find the current documentation quite clear and easy to use. My</tt><br>
<tt>only issue is that some functions are just not documented.</tt><br>
<br>
</body></html>
______________________________________________________________________
OpenSSL Project http://www.openssl.org
User Support Mailing List openssl-users@openssl.org
Automated List Manager majordomo@openssl.org
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic