On Fri, Feb 26, 2016 at 12:10:09PM -0500, Jeffrey Walton wrote:
> > I'd like to propose a policy of no bug fixes to undocumented public
> > interfaces. If the interface is useful enough to fix, it has to be
> > documented. Anyone care to produce manpages for EC_KEY_priv2buf or
> > EC_KEY_priv2oct?
> >
> Correct me if I am wrong... API's that start with capitol letters are
> public. Private interfaces use lowercase letters.
> Documented/undocumented does not really factor things.
You're wrong. Once OpenSSL's past sins are remediated, public
interfaces are precisely those that are documented. For now, public
interfaces are either macros or functions and global variables
those whose symbols are exported by the libssl and libcrypto shared
libraries. This is not a good place to be.
> If OpenSSL wants to make it private so that its should not be called
> and it won't be maintained, then the symbol should be changed to
> ec_key_priv2oct.
Undocumented functions have no public "contract", and should not
be used. Sadly we're not quite there yet, but the way to get there
is at least always update the documentation of any functions that
are updated. We also have to document functions that are not
updated, but that does not change the wisdom of the proposed policy.
One reason to update the documentation, is that one will often find
that documenting a function will make one think harder about how it
is really supposed to behave, potentially improving the code and/or
avoiding mistakes.
--
Viktor.
--
openssl-dev mailing list
To unsubscribe: https://mta.openssl.org/mailman/listinfo/openssl-dev
