Re: [lmi] doxygen

[Vadim Zeitlin]

On Wed, 11 Mar 2009 23:35:59 +0000 Greg Chicares <address@hidden> wrote:

GC> I strongly agree with the author quoted here (search for "Yuck!"):
GC>   http://lists.nongnu.org/archive/html/lmi/2007-02/msg00029.html

 I also dislike special markup in the comments which is [one of the
reasons] why we still don't put Doxygen comments inline in wx sources but
IMO once you start using Doxygen or similar system you need to use its
markup as otherwise the quality of the generated documentation is poor. IOW
the comments themselves are surely more readable without markup but the
goal of using such system is to produce readable HTML (or PDF or whatever)
documentation, otherwise why use it at all?

GC> Accordingly, I avoid the libstdc++ doxygen style:
GC>   http://gcc.gnu.org/ml/libstdc++/2004-07/msg00132.html
GC> though that message contains useful commentary on option settings.
GC> 
GC> Speaking of which...does wx have a well-chosen set of doxygen
GC> options that lmi might adopt or at least adapt?

 The options used by wx are in docs/doxygen/Doxyfile_inc. Most of this file
just defines some aliases, i.e. more markup (albeit custom to wx) so is
probably not very interesting to you. The main change compared with the
defaults is probably "JAVADOC_AUTOBRIEF = YES", IMHO this is very
convenient. I didn't experiment much with ABBREVIATE_BRIEF though (as I
don't think it was in the first Doxygen versions I used) so maybe the
current set of options is not optimal for the new Doxygen versions.

GC> And has wx automated the process of generating doxygen output,

 Yes, documentation at http://docs.wxwidgets.org/trunk/ is generated using
docs/doxygen/regen.sh but this is script is pretty trivial.

GC> e.g. by using the pipeline technique suggested in item seventeen of the
GC> doxygen FAQ?
GC> 
GC>   http://www.stack.nl/~dimitri/doxygen/faq.html
GC>       ( cat Doxyfile ; echo "PROJECT_NUMBER=1.0" ) | doxygen -

 Ah, I/we didn't think about this (and didn't read the FAQ, shame on us).
So we use a different approach: all common options are in the above
mentioned Doxyfile_inc and we have e.g. Doxyfile_html with HTML-specific
options. This is less elegant but works just fine.

GC> Aside from that automation, the tasks seem to be as follows.
GC> 
GC> * Ensure that doxygen uses all the comments we hope it will.
GC> 
GC> For example, in this block:
GC> 
GC>   /// Functions for testing, intended to be implemented in a shared
GC>   /// library to demonstrate that alerts can be raised there and
GC>   /// processed in the main application.
GC> 
GC>   void LMI_SO test_status();
GC>   void LMI_SO test_warning();
GC> 
GC> I think doxygen matches the '///' block with the first function,
GC> and leaves the second undocumented.

 Yes. I think you need to either use "//@{" and "//@}" around the functions
to make the comment apply to both or use @ingroup. At least I don't know of
any other way.

GC>   /// Class Foo does...whatever.
GC> 
GC>   #ifdef FOO
GC>   class Foo {...
GC> 
GC> which probably matches class Foo's documentation to macro FOO.

 No, I don't think so, AFAIK this would only be the case if you had
"#define FOO".

GC> * Change '//' to '///' comments where appropriate.
GC> 
GC> For instance, a mechanical 's|//|///|' would seem correct here:
GC> 
GC>   // With cgicc, the most natural way to treat any alert that must be
GC>   // brought to the user's attention is to throw an exception and let
GC>   // a higher-level routine catch and display it. It might be desirable
GC>   // to write a log file, too.
GC> 
GC>   void warning_alert(std::string const& s)
GC> 
GC> but in general the work cannot be mechanized: I suppose it must be
GC> carefully performed and checked by hand.

 There wouldn't be much harm in doing it mechanically first and checking
(and correcting) later IMHO. It will be easier to detect mistakes reading
the generated documentation and not the comments in the sources.

GC> * Write high-level overviews. Probably this is the most serious
GC> shortcoming of our documentation: all the trees are labeled, but that
GC> doesn't help you find your way through the forest.

 Exactly. This is my personal peeve with Doxygen, although, of course, I'm
being unfair as it has nothing to do with Doxygen itself and is a problem
with people using it. But the fact is that it's not enough to document all
the classes and functions in the project to have documentation for it and
most projects using Doxygen seem to stop at this stage. Of course, the rest
is much more difficult and time-consuming -- but also most useful.

 One item which you might add to the list:

* Escape (some) '@', '<' and '>' characters in the sources. They have
  special meaning for Doxygen and most often you'll need to use \< and \>.

Also, you will probably get tons of warnings from Doxygen initially. It
would be better to fix them because even though many of them are harmless
there can also be useful ones among them and I prefer to keep docs
generation as warning free as compilation for my own projects and for the
same reasons.

 Regards,
VZ