[zeromq-dev] Documentation Proposal

[Martin Sustrik]

Pieter Hintjens wrote:
> On Fri, Jul 9, 2010 at 11:08 PM, Peter Alexander <vel.accel at gmail.com> 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