Re: [lmi] doxygen

[Vadim Zeitlin]

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> 
GC> Yes, please, though it's not at all urgent. I'd like to hear your
GC> observations.

 First of all I wanted to check if Doxygen would be able to parse the
existing comments at all. I tried running it with default configuration
file (i.e. with WARNINGS on but WARN_NO_PARAMDOC off) but this, of course,
resulted in a huge number of warnings:

        % doxygen|&wc -l
        2251

so I had to turn WARN_IF_UNDOCUMENTED off. Surprisingly (for me), this left
only 3 other warnings:

        % doxygen
        fenv_lmi.hpp:64: Warning: explicit link request to 'pragma' could not 
be resolved
        mvc_controller.hpp:145: Warning: Unsupported xml/html tag <object> found
        xml_serialize.hpp:86: Warning: lonely <item> tag found

I don't understand the first one and it definitely looks like a bug in
Doxygen (there are no links there nor even occurrences of 'pragma' inside
Doxygen comments so I have no idea what is this about). The two other ones
are due to Doxygen interpreting <foo> specially and the only workaround is,
AFAIK, use "&lt;foo&gt;" instead which is almost certainly too ugly for you
to consider. So we'll have to live with these warnings, I guess.

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.

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. 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
        function, typedef, enum or preprocessor definition you must first
        document the file that contains it (usually this will be a header
        file, because that file contains the information that is exported
        to other source files).

        Let's repeat that, because it is often overlooked: to document
        global objects (functions, typedefs, enum, macros, etc), you must
        document the file in which they are defined. In other words, there
        must at least be a

        /*! \file */ 

        or a

        /** @file */ 

        line in this file.


I don't know if you can accept this small uglification. If not I can think
of only 2 solutions:

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).

2. Submit a patch allowing the documentation to be taken into account even
   in not documented files. Looking at Doxygen TODO list[2], this appears
   as item #3 on it so presumably such a patch would be accepted. It also
   has difficulty of 4 (1 is lowest, 10 is highest) which probably means
   this shouldn't be extraordinarily difficult to do neither but I've never
   worked with Doxygen sources so I'd really need to at least look at them
   if this possibility is interesting at all.


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.


GC> But what about high-level documentation--isn't that the biggest
GC> deficiency?

 Of course, there is absolutely no doubt about it. This is my pet peeve
with Doxygen (although it's none of its fault, of course): many people
think that it's enough to document all functions/classes and obtain nice
looking HTML on output to declare that the project is well-documented when
nothing could be further from the truth. I've seen plenty of project where
Doxygen documentation obscured the few bits of really useful information
found in the comments in the sources. For any non-trivial project overview
of how it works is indispensable. But this has nothing to do with Doxygen
other than the fact that you can easily include separate files (with such
overviews) in Doxygen-generated documentation. The main problem is writing
such documentation and making it really clear and useful. And I have no
original ideas about solving it...


 BTW, I've put the configuration file I used with Doxygen online[3]. It has
few changes compared to the default one, for the boolean options the values
that I changed are in lower case ("yes" or "no") whereas the defaults are
always in upper case.

 Regards,
VZ

[1] http://www.stack.nl/~dimitri/doxygen/docblocks.html#structuralcommands
[2] http://www.doxygen.nl/todo.html
[3] http://www.tt-solutions.com/vz/lmi/Doxyfile