Re: [lmi] doxygen

[Greg Chicares]

On 2010-03-27 12:26Z, Vadim Zeitlin wrote:
> On Fri, 26 Mar 2010 15:23:09 +0000 Greg Chicares <address@hidden> wrote:
> 
> GC> > I didn't try running Doxygen on LMI sources (I could try it if
> GC> > you're curious...)
[...]
> GC> > but I'm pretty sure that you're not going to get
> GC> > anything nice out of it.
> GC> 
> GC> That depends on how we define "nice".
> 
>  This is a difficult question but, to steal a well-known definition of
> another term, I know it when I see it. And this
> 
>       http://www.tt-solutions.com/vz/lmi/docs/
> 
> is not nice.

The items that actually have some documentation aren't all bad.
For instance, this:
  http://www.tt-solutions.com/vz/lmi/docs/classtn__range.html
isn't light-years away from being nice--depending, again, on your
definition of nice.

Overall, it's a brick wall with most of the bricks missing. But we do
have a workable recipe for making more bricks. And we already have a
considerable amount of unprocessed clay in non-'///' comments.

> GC> To the (limited but definitely not zero) extent that I've
> GC> followed the simple
> GC>   /// Commentary on foo()
> GC>   [blank line]
> GC>   void foo()
> GC> paradigm, we've got the function-level details covered.
> 
>  Unfortunately this isn't the case. For instance, neither
> numeric_io_cast<>() nor stream_cast<>() is documented.

They're present:
  http://www.tt-solutions.com/vz/lmi/docs/numeric__io__cast_8hpp.html
  http://www.tt-solutions.com/vz/lmi/docs/stream__cast_8hpp.html
and you can get to them from "File Members" here:
  http://www.tt-solutions.com/vz/lmi/docs/globals.html
but I guess you're saying they should appear in some other list, too?

> The reason for this
> is explained in Doxygen manual[1]:
> 
>       To document a member of a C++ class, you must also document the
>       class itself. The same holds for namespaces. To document a global C

Okay, that paradigm works for classes--e.g., this member function:
  void tn_range<Number, Trammel>::minimum_and_maximum()
did get documented, here:
  
http://www.tt-solutions.com/vz/lmi/docs/classtn__range.html#aa77811979310043ae6d9f17055a6f85c
from '///' comments in 'tn_range.tpp', apparently because
class tn_range has '///' comments in 'tn_range.hpp'. However...

>       class itself. The same holds for namespaces. To document a global C
>       function, typedef, enum or preprocessor definition you must first
>       document the file that contains it

Well, that's unfortunate--apparently doxygen wants one of these:
>       /*! \file */ 
>       /** @file */ 
in each file, in order to...build some extra index of such items?

> I don't know if you can accept this small uglification.

I'd rather avoid that, if your preprocessing idea works well...

> 1. Preprocess LMI files before passing them to Doxygen. This step could add
>    "@file" comment to all headers and also replace '<' with "&lt;" for
>    example. This shouldn't be too difficult to implement and shouldn't take
>    long (especially if it can be done in something other than C++, e.g.
>    Perl or Python).

We don't have to introduce a dependency on another tool, e.g.:
  for z in *; do sed -i $z -e"1i/** @$z */"; done
although it'd be nicer to use that as a filter instead of
(over)writing a file, if doxygen allows.

> 2. Submit a patch allowing the documentation to be taken into account even
>    in not documented files.

I suppose we should spend our time elsewhere than on (2),
unless it's really easy.

> In any case it seems useless to proceed with further testing Doxygen output
> before this is fixed as much (most?) of the documentation currently doesn't
> appear in HTML at all.

Probably (1) would be an easy, cost-effective workaround.
But first, can you point me to an example of what's missing,
in some other project's doxygen documentation? For xmlwrapp,
e.g., I see the same "Namespaces - Classes - Files" headings.