[lmi] doxygen [Was: patch to remove unused argument from numeric_io_cast()]

[Greg Chicares]

On 2010-03-24 15:00Z, Vadim Zeitlin wrote:
> On Wed, 24 Mar 2010 13:34:51 +0000 Greg Chicares <address@hidden> wrote:
> 
> GC> [0] "special markup ... but I prefer to avoid it"
> 
>  This would take even further OT again but IME you can't avoid it.

We can't afford it. The documentation we have in incomplete--its
substance is insufficient--and that's worse than any shortcoming
in the way it's presented.

> You can
> have either readable source code (LMI) or readable documentation (any
> typical project using Doxygen) or both at the cost of duplication (wx keeps
> its headers readable by putting Doxygen documentation in another set of
> headers).

I prefer readable source code, along with whatever documentation
doxygen is able to produce from it without any doxygen-specific
markup (beyond beginning comments with '///'). The free variable
is thus "readable documentation"; but it might very well turn out
to be readable enough.

If I learn of a slightly different way to write source code that
works better with doxygen (while still avoiding markup as above),
then I strive to adopt it for new code, and to apply it to old
code as that gets refactored. For example:

  /// culminate(): Perform postprocessing: call culminate_ui(); then
  /// display a warning if the iteration counter doesn't equal its
  /// maximum, unless the operation was cancelled.

I think it would be better to move that comment out of the
header, writing it just before the implementation instead:

  /// culminate(): Perform postprocessing: call culminate_ui(); then
  /// display a warning if the iteration counter doesn't equal its
  /// maximum, unless the operation was cancelled.

  void progress_meter::culminate()

Then, AIUI, doxygen will automatically DTRT with it. We'd no
longer have all such comments packed together in the header, but
they'd be organized together in the doxygen html; and it wouldn't
be too hard to page through the implementation to read them all,
so nothing is really lost even if we never run doxygen.

> I didn't try running Doxygen on LMI sources (I could try it if
> you're curious...)

Yes, please, though it's not at all urgent. I'd like to hear your
observations.

> but I'm pretty sure that you're not going to get
> anything nice out of it.

That depends on how we define "nice".

Documentation that exists is nicer than documentation that
doesn't. There is already potential html documentation that we
could bring into existence with little effort, and it would be
more impressive to corporate managers than even perfect inline
documentation.

To the (limited but definitely not zero) extent that I've
followed the simple
  /// Commentary on foo()
  [blank line]
  void foo()
paradigm, we've got the function-level details covered. To the
extent that we already have comments that don't yet follow that
paradigm, refactoring them so that they do is fairly trivial.
But what about high-level documentation--isn't that the biggest
deficiency?

Take the census manager as an example. You can easily find out
what CensusView::column_value_varies_across_cells() does: that's
documented. It's harder to tell why the operation it performs is
actually useful, or when it should be performed. But hardest of
all is to figure out what a census manager's purpose might be,
wouldn't you say?