On Fri, Feb 26, 2016 at 12:50:24PM -0500, Jeffrey Walton wrote: > > Nonsense. Source code is not API documentation, it is an > > implementation, not an interface contract. > > I'm not sure I'd consider it nonsense.
Comments in source code are not documentation, they explain the internals of the implementation, not the contract. Users of a library need to depend on documented semantics, not implementation artefacts. > Studying source code on occasion is simply par for the course when > working with open source libraries. Here, by "open source" you mean poorly maintained. I'd like OpenSSL to leave that legacy behind. Not all open source software is poorly maintained and under-documented. > In my naiveness, if you want something to be private, then you don't > expose it to the outside world. That too, but not documenting an interface should be sufficient to dissuade users from relying on it. Sadly, important parts of OpenSSL are not yet documented, and I am proposing we become more aggressive about fixing that. One way forward is to ensure that changes must come with documentation, created if missing, updated if the interface is extended, or changed incompatibly. > It also seems like if a function leaks into a public header, then you > state that its private and it should not be called. What's the > aversion to a clearly and succinctly stating something? All I'm saying is that documentation is not optional. Neither source code nor header files are documentation. > > Bug fixes to undocumented functions will be buggy, and the > > documentation will never happen. We need to improve code quality, > > a good part of that is having documentation. > > If the code is > buggy, then it should be fixed or removed. There's no middle ground. It must be fixed *and* documented. Over and out. -- Viktor. -- openssl-dev mailing list To unsubscribe: https://mta.openssl.org/mailman/listinfo/openssl-dev