On 24. 6. 2009, at 22:32, Del Merritt wrote:
As to how one tracks commentary/documentation to the actual code, I
think a little hint from Don Knuth's "Literate Programming" is in
order:
http://www.literateprogramming.com/
One current example of it is Javadoc, and I see some hooks in the
OOo code that would support a processor running over the source (a
la Doxygen or any number of other parsers). Someone gave me a link
(which I've lost) on #dev.o.o to a site that posts Doxygen output,
and it was interesting to look at. But Javadoc on its own isn't
sufficient, for reasons mostly of scale. For example, I didn't find
any use of a summary or main page. Instead, one was dropped right
into a complex list of functions and files and monster diagrams. A
problem of seeing the forest for all the trees.
I am not sure Knuth-like literate programming would work for us. I
rather think that (a) the code itself should be clear enough to not
need extensive inline documentation (apart from the occasional hint on
tricky parts), (b) the various APIs should be documented concisely
with Javadoc and similar, and (c) high-level documentation of how
larger parts of OOo work should exist. Of those, (a) is covered more
or less well (YMMV), (b) is covered pretty well I would say, and,
sure, (c) is the problematic part. Some of it is there and spread
across places (and often enough outdated), but I doubt that either LP
or Javadoc could substitute for the demand for well-written, high-
level documents that people are passionate enough about to keep in
reasonable sync to the actual code (however we would be able to
satisfy that demand...).
-Stephan
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
