pasha murat wrote:
> hi - I looked at the URL you mentioned - the docs look pretty nice!
> just a couple of quick comments:
> - in what it calls "TH1 Class Reference" doxygen doesn't distinguish
> between the functions and the data members which sort of inconvenient
> ...
> - I then looked at what is called "File reference" - example is given by
> http://www-kp3.gsi.de/www/dox/root_raw_dev/html/H_H2.cxx.html
> why does doxygen take all the comments out of what it
What I generated with doxygen was some sort of an `class browser'
(under dox/root_raw) and some sort of a `source browser' (under
dox.root_raw_dev). That should *not be confused* with a real
documentation.
doxygen expects the text of the documentation in `tagged' comment
blocks, e.g. in the form
/*!
...
*/
to distinguish between documentation and simple code comments. Such a
docu block documents the following construct, unless special tags
overwrite this. Default is that only documented entities show up in
the output. For the ROOT demo, I configured doxygen to generate
a header for all entities, whether documented or not, so I effectively
got a simple `class browser', and by enabling the source view option,
I got some sort of `source browser'.
I actually disagree with your requirement of
> - generation of the documentaion should not require instrumenting
> the sources with some metasymbols (which I believe are required by doxygen)
First, one has to distinguish between real documentation and simple code
annotation. That already requires constructs like the /*! ... */ and such.
The extra letter should stop us to write a documentation.
Second, documentation has a structure, like every document, and not all of
it is implicit in the context. A docu block in front of a member function
definition clearly relates to this function and will be put in the appropriate
class documentation. But what to do with a global function like
Vector operator+(Matrix& m, Vector& v) {...}
Should it be documented as global function, which it technically is, or
for example be part of the documentation of the Class Matrix, where you
are more likely to look for it. In doxygen you'd put a
\relates Matrix
into the docu block of this function, and as a consequence, the documentation
will be included in the class Matrix and show up unter the section heading
Friends And Related Function Documentation
I see no way to get for example this information in a reliable fashion
just from the context.
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