> Del Merritt wrote: >> Anyway, does anyone care to offer some history as to why both of these >> architectural pages seem to have fallen quietly by the side? >> > Hi Del, > > well, you gave the answer to that yourself - it's not automatically > generated from the source code & thus quickly outdated. I maintain a > subset of doxygen-generated documentation pages here > > http://docs.go-oo.org/
Thank you, Thorsten; it is indeed your site that I had a link to. I am a Doxygen enthusiast, and was pleased to see that you/someone had taken the time to set up this repository. > , which in principle could also contain medium- to high-level design > documentation (see e.g. > http://hci.iwr.uni-heidelberg.de/vigra/doc/vigra/index.html for a > different project) - if someone would write it. An OOo example in situ is: http://docs.go-oo.org/sw/html/index.html Or, as you allude, it's an example of what isn't but could be. I think the "Main Page" of Doxygen/Javadoc documentation is an ideal place for some or all of the high-level narrative documentation, that in turn points to key classes or other parts of the documentation. > One of the specific problems of OOo is the fact that so much code is > already written, and only a comparatively small fraction gets > touched or even written anew per release; so in a commercial > setting, there's little short-term incentive to demand proper > documentation for the code touched (requesting after-the-fact > documentation of the existing, sometimes ages-old code, is even more > illusionary). I hear this loud and clear. It's a classic case of the Dusty Deck(tm), and there is the ancillary problem of the need to code-review and QA "comment only changes". To some it seems a waste of time, and if the "some" include those doing routine maintenance or other more interesting projects, it gets the short shrift. > I'm by no means happy about that, and well aware of the fact how > much of a barrier of entry this is. I would be interested in learning more of the infrastructure of your site - for example, the "Last updated" comment at the bottom of http://docs.go-oo.org/ is May 28, 2009, and there's no indication of what svn checkpoint/release/milestone is documented - and how routine doxygen runs could be performed on the code base, a la {OpenGrok's search mechanism. In my Perfect World, {OpenGrok would do what it does, and in addition would have a live link to the Doxygen documentation at various levels. This would handle milestone-specific documentation. I've helped institute automated Doxygen runs in the past and so this isn't just another NiceToHave whine without any offer to help. But I'd need to know how this could be best folded in to the existing tools/resources and who the people are who make that all happen. I see the issues as coming from two camps: 1) Setting up the tool suite that does a "automagic" Doxygen run on milestones/CWSs as changes occur, ideally tied in to an existing system like {OpenGrok so that it's an immediate benefit to developers. A sub-issue here is that Doxygen is not terribly make-friendly (at least of my last direct experience), and thus incremental documentation updates can be resource intensive. 2) Getting developers on board with regard to making best/better/any use of Javadoc/Doxygen in-line documentation features. This includes module/class/app-specific documentation along with higher-level stuff. Regards, -Del > Regards, > > -- Thorsten > --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
