Hi rooters,
I liked Pasha Murat's list of requirements for the functionality of
documentation tools. Before one goes into deeper details, I'd like
to make a few more general points.
Imho one should strictly distinguish between a
user documentation
developer documentation
The user doc describes the *interface*, so it will state what the purpose
of a class is and describe public and protected members, hopefully with
examples and a tutorial. *NOTHING more*.
The developer doc will in addition cover the private members and may contain
information about the *implementation*. It's highly convenient to include
a hyperlinked rendition of the source and for example links to revision control
system.
It is obvious that both versions should be generated from the same annotated
source, just with different options of the generating program.
* The user doc should contain all the information you need to write an
application based on the ROOT framework.
* The developer doc should of course be available to all, but be needed only
by those working on the framework itself, usually a small fraction of the
community.
It worries me a little that the `source browser' is considered one of the
more important features in the ROOT documentation. It should be superfluous
for most, applications should be written against an interface specification,
not against an implementation.
Cheers, Walter
--
Walter F.J. Mueller Mail: W.F.J.Mueller@gsi.de
GSI, Abteilung KP3 Phone: +49-6159-71-2766
D-64291 Darmstadt FAX: +49-6159-71-2989
WWW: http://www-kp3.gsi.de/www/kp3/people/mueller.html
PGP: http://www-kp3.gsi.de/~mueller/pgp.shtml
This archive was generated by hypermail 2b29 : Tue Jan 04 2000 - 00:43:40 MET