lmi
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[lmi] doxygen


From: Greg Chicares
Subject: [lmi] doxygen
Date: Wed, 11 Mar 2009 23:35:59 +0000
User-agent: Thunderbird 2.0.0.19 (Windows/20081209)

I concur with the POV Vadim expresses in the last paragraph here:
  http://lists.nongnu.org/archive/html/lmi/2009-03/msg00023.html
so let us hereby declare doxygen to be lmi's official documentation
system. It's easy to make such a declaration, but producing results
takes planning and work. I'd be very glad to hear more about the wx
conversion to doxygen, which might provide practical insight into
the points listed (or any omitted) below.

lmi already contains about six thousand lines of '///' comments
designed for doxygen, with more to come: I continually change old
'//' comments to '///' as convenient opportunities arise. The problem
is that some of them wouldn't be recognized properly by doxygen,
whose rules are somewhat arcane. AFAIK, the following exemplar always
does the right thing:

   /// Doxygen comment. This can span multiple lines.
   /// Write a blank line after this '///' block:

   [declaration of class, or definition of function]

and that seems sufficient for all of lmi's needs, as well as simple
enough to memorize and use consistently.

I strongly agree with the author quoted here (search for "Yuck!"):
  http://lists.nongnu.org/archive/html/lmi/2007-02/msg00029.html
Accordingly, I avoid the libstdc++ doxygen style:
  http://gcc.gnu.org/ml/libstdc++/2004-07/msg00132.html
though that message contains useful commentary on option settings.

Speaking of which...does wx have a well-chosen set of doxygen
options that lmi might adopt or at least adapt?

And has wx automated the process of generating doxygen output, e.g.
by using the pipeline technique suggested in item seventeen of the
doxygen FAQ?

  http://www.stack.nl/~dimitri/doxygen/faq.html
      ( cat Doxyfile ; echo "PROJECT_NUMBER=1.0" ) | doxygen -

I'm thinking that we should automate this as part of a monthly
release procedure, putting the results online here:
  http://www.nongnu.org/lmi/doxygen/

Aside from that automation, the tasks seem to be as follows.

* Ensure that doxygen uses all the comments we hope it will.

For example, in this block:

  /// Functions for testing, intended to be implemented in a shared
  /// library to demonstrate that alerts can be raised there and
  /// processed in the main application.

  void LMI_SO test_status();
  void LMI_SO test_warning();

I think doxygen matches the '///' block with the first function,
and leaves the second undocumented. There may be other surprises,
like

  /// Class Foo does...whatever.

  #ifdef FOO
  class Foo {...

which probably matches class Foo's documentation to macro FOO.

* Change '//' to '///' comments where appropriate.

For instance, a mechanical 's|//|///|' would seem correct here:

  // With cgicc, the most natural way to treat any alert that must be
  // brought to the user's attention is to throw an exception and let
  // a higher-level routine catch and display it. It might be desirable
  // to write a log file, too.

  void warning_alert(std::string const& s)

but in general the work cannot be mechanized: I suppose it must be
carefully performed and checked by hand.

* Review doxygen output and revise comments that don't work well.

In this example:

  /// Design notes: numeric stream output.
  /// [several meaningful lines]

  inline std::ostream& operator<<(std::ostream& os, any_entity const& z)

the first '///' line might appear after a doxygen heading like
"Member function description", so the words "design notes" will
become superfluous at best.

* Fill in documentation where there's none.

* Write high-level overviews. Probably this is the most serious
shortcoming of our documentation: all the trees are labeled, but that
doesn't help you find your way through the forest. Some overviews
exist already, e.g., preceding this oddity:

  namespace model_view_controller{} // doxygen workaround.

which I wrote in the untested hope that the comment block would be
associated with...well, something. Probably there's a better way.




reply via email to

[Prev in Thread] Current Thread [Next in Thread]