[zeromq-dev] Documentation Proposal
sustrik at 250bpm.com
Sat Jul 10 07:38:23 CEST 2010
Pieter Hintjens wrote:
> On Fri, Jul 9, 2010 at 11:08 PM, Peter Alexander <vel.accel at gmail.com> wrote:
> Peter, it looks really nice and this looks like the right way to host
> the generated source code docs.
There are several possible advantages of this:
1. Things like class hierarchies and generated call graphs can make it
easier for new people to catch up with the architecture of the product.
2. If made public, it's an incentive to write the comments in a way that
makes sense even without seeing the actual code, i.e. more clear and
coherent, giving more context.
3. Looking at some graphs
makes you think about how the architecture can be simplified.
As for the actual publishing of the docs, I've been thinking about it a
bit and here are my thoughts:
1. It doesn't make sense to distribute the generated docs with the
package. Packages are for users. Users don't need detailed code
documentation. Developers, on the other hand, are presumably not using
packages, rather checking out the recent version from trunk.
2. The documentation has to tightly correspond to the version you are
developing otherwise it can do more harm than good.
3. Still, *some* version of internal documentation should be published
so that people can get a quick understanding of the codebase even
without downloading the actual code.
More information about the zeromq-dev