On Sat, Jul 10, 2010 at 1:38 AM, Martin Sustrik <sust...@250bpm.com> wrote: > Pieter Hintjens wrote: >> On Fri, Jul 9, 2010 at 11:08 PM, Peter Alexander <vel.ac...@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. >
Its not needed by users because zeromq is beautiful in api simplicity. I don't even think it needs to be distributed with trunk (maybe just the Doxyfile config file). Web based public access would suffice. > 2. The documentation has to tightly correspond to the version you are > developing otherwise it can do more harm than good. > Publicly, only for mainline development snapshots (zeromq/zeromq2 -- master). My thought was to either have a commit hook (if possible) to automatically update/generate the hosted doc per commit, or to have a local script and a cron job to update/generate on a timely basis like once a day or so. > 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 > zeromq-dev@lists.zeromq.org > http://lists.zeromq.org/mailman/listinfo/zeromq-dev > _______________________________________________ zeromq-dev mailing list zeromq-dev@lists.zeromq.org http://lists.zeromq.org/mailman/listinfo/zeromq-dev
