On Wed, Apr 23, 2014 at 10:23:11PM -0400, Daniel Kahn Gillmor wrote:
> >> A serious way to fix this is to have the documentation produced *from*
> >> the code, so that it gets upgraded in sync. For example, neither
> >> x509(1ssl) nor "openssl x509 -help" ever mention the -sha256 option,
> >> but that option has been supported for years.
> >
> > No, that won't work well.
>
> out of curiosity, why not? At the very least the output of "openssl
> x509 -help" should be derived from the same code that actually parses
> the "openssl x509" command-line options. shouldn't these be able to be
> kept in sync within the code?
Because too often a new feature impacts multiple documents, and
API documentation requires more text than typically produced by
doxygen and the like.
> It's easy to know reject a patch because it has no documentation
> changes. I agree that would be a good policy, worth implementing and
> abiding by.
>
> But it's much harder to know that *all relevant documentation* has been
> properly updated, especially with a project that covers as much ground
> as OpenSSL does.
If the reviewer of a patch cannot determine whether all relevant
documentation has been updated, he or she has failed to review the
patch. What's more, undocumented features are difficult to review,
because the goals of the feature are under-specified.
Being forced to document a new feature also tends to discourage
poorly thought-out ideas that are difficult to document because
they introduce behaviour too difficult to explain or too clumsy to
admit in writing.
--
Viktor.
______________________________________________________________________
OpenSSL Project http://www.openssl.org
Development Mailing List [email protected]
Automated List Manager [email protected]
