Pieter Hintjens wrote: > On Fri, Jul 9, 2010 at 11:08 PM, Peter Alexander <[email protected]> wrote: > >> http://travlr.github.com/zeromq2/ > > 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 (http://travlr.github.com/zeromq2/classzmq_1_1socket__base__t.html) 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. Thoughts? Martin _______________________________________________ zeromq-dev mailing list [email protected] http://lists.zeromq.org/mailman/listinfo/zeromq-dev
