Re: [lmi] doxygen

[Greg Chicares]

On 2010-03-27 18:12Z, Vadim Zeitlin wrote:
> On Sat, 27 Mar 2010 18:01:37 +0100 Vaclav Slavik <address@hidden> wrote:
> 
> VS> On Sat, 2010-03-27 at 13:26 +0100, Vadim Zeitlin wrote:
> VS> > I don't know if you can accept this small uglification. If not I can
> VS> > think of only 2 solutions:
> VS> 
> VS> 3. Set EXTRACT_ALL = YES in Doxyfile to generate documentation for
> VS>    everything, documented or not. 
> VS> 
> VS> Or am I missing something?
> 
>  No, it was me. I didn't realize that EXTRACT_ALL would help with this, I
> thought it didn't change anything for the _documented_ stuff but clearly it
> does and it did create the documentation for numeric_io_cast<> [1].

I should have finished reading the thread before replying to that.

>  So while it has its drawbacks, namely:
> 
> - Much longer doxygen running time (almost 3 minutes here) which is not
>   very important probably.

I agree, that's not very important.

> It also results in some pretty hefty
>   documentation (114M of HTML output, including the diagrams but excluding
>   the code listings which I disabled) but this might be considered a good
>   thing if you measure documentation quality by its quantity :-)

It would be really nice to add this stuff to our savannah webpages
  http://www.nongnu.org/lmi/
and update it monthly. But I hesitate to put 114M there. Would it
be much smaller if we omitted the graphics? I kind of like having
links to the source, though--wouldn't that add "only" 6M or so?

> it should still probably be used and I've updated the copy of Doxyfile on
> the web [2] to use it.

That's very helpful to me. There are so *many* options.

>  We have a few more warnings with it:
> 
> numeric_io_cast.hpp:101: Warning: Found unknown command `\1'
> regex_test.cpp:151: Warning: Unsupported xml/html tag <LF> found
> regex_test.cpp:151: Warning: Unsupported xml/html tag <CR> found
> regex_test.cpp:151: Warning: Unsupported xml/html tag <LS> found
> regex_test.cpp:151: Warning: Unsupported xml/html tag <PS> found

That's a literal quote from ECMA-262:
///   the set of all characters except the four line terminator
///   characters <LF>, <CR>, <LS>, or <PS>

which comes through okay in the generated html:

  http://www.tt-solutions.com/vz/lmi/docs/regex__test_8cpp.html
  the four line terminator characters <LF>, <CR>, <LS>, or <PS>

so ignoring those warnings might be easier than looking for a
more graceful workaround.

It's worth remembering that doxygen does something nice with this:

/// TR1, there seem to be only two viable options:
///  - use a vectorized approach such as this; or
///  - write regexen with
///    - "[^\\n]" instead of '.', and
///    - "\n" instead of '^' and '$' anchors

> test_coding_rules.cpp:306: Warning: Found unknown command `\f'
> test_coding_rules.cpp:306: Warning: Found unknown command `\r'
> test_coding_rules.cpp:306: Warning: Found unknown command `\t'
> test_coding_rules.cpp:306: Warning: Found unknown command `\v'

Here's the code:
/// Throw if the file contains '\f', '\r', '\t', or '\v', except in

  http://www.tt-solutions.com/vz/lmi/docs/test__coding__rules_8cpp.html
  Throw if the file contains '', '', '', or ''

I could write FF CR HT VT, but that would be less clear. Maybe
writing <\f> would trick doxygen into passing it through unchanged,
as seemed to happen with <LF> above?

> test_coding_rules.cpp:370: Warning: explicit link request to 'include' could 
> not be resolved

/// canonical form '#include "unutterable"' (its name can't be uttered

Here, doxygen strips the '#':
  http://www.tt-solutions.com/vz/lmi/docs/test__coding__rules_8cpp.html
  include directive must take the canonical form 'include "unutterable"'
which is unfortunate but doesn't make the comment incomprehensible.

Is there any doxygen option to inhibit this '#' removal? If '#' is
doxygen-specific markup for a doxygen "link", then can we declare that
we don't use any such "link"?

> value_cast_test.cpp:468: Warning: Found unknown command `\1'
> fenv_lmi.hpp:64: Warning: explicit link request to 'pragma' could not be 
> resolved

Maybe it's confused by
#       pragma STDC FENV_ACCESS ON
?

> mvc_controller.hpp:145: Warning: Unsupported xml/html tag <object> found

/// View: An '.xrc' file that specifies control layout. Control names
/// in the '.xrc' file must match the Model's data-member names: e.g.,
///   <object class="wxDatePickerCtrl" name="DateOfBirth">
/// requires
///   wxDateTime Model::DateOfBirth; // Same name.
/// which may be accessed by the same string:
///   Model["DateOfBirth"] // As above.

The generated documentation
  http://www.tt-solutions.com/vz/lmi/docs/namespacemodel__view__controller.html
handles the <object> tag:

  Control names in the '.xrc' file must match the Model's data-member
  names: e.g., <object class="wxDatePickerCtrl" name="DateOfBirth">
  requires wxDateTime Model::DateOfBirth; // Same name. which may be
  accessed by the same string: Model["DateOfBirth"] // As above.

but I guess I can't expect doxygen to preserve my indentation. As
this example shows, somebody needs to read all the documentation in
order to identify the techniques that don't work; that's laborious.

> xml_serialize.hpp:86: Warning: lonely <item> tag found

/// from_xml() reads only <item> elements, ignoring other elements

Apparently it deletes '<item>' here:

  
http://www.tt-solutions.com/vz/lmi/docs/structxml__serialize_1_1xml__sequence__io.html
  from_xml()  reads only elements, ignoring other elements

which renders the documentation nonsensical. Why was <LF> okay above?

>  The ones about '\1' &c are annoying because the '\1' doesn't appear in the
> output at all, see [1] again: in the last paragraph of the function
> documentation you only see '' which makes the description incomprehensible.

/// at first: it treats them as decimal numbers. Thus, casting from
/// std::string("1") to char returns '\1', and casting that result

becomes

  http://www.tt-solutions.com/vz/lmi/docs/numeric__io__cast_8hpp.html
  casting from std::string("1") to char returns ''

Is there an option that tells doxygen not to try interpreting
backslash as the beginning of doxygen-specific markup?

> Maybe we could use some workaround like "ASCII 1" or "^A" instead of \1?

I'm sure I don't know what "^A" is, and even "ASCII 1" is hard for me
to parse.

Wait--maybe double-quotes are the answer--this code:

///    - "\n" instead of '^' and '$' anchors
///    and prepend a '\n' sentry to the string to be searched (and

becomes:

  http://www.tt-solutions.com/vz/lmi/docs/regex__test_8cpp.html
  "\n" instead of '^' and '$' anchors and prepend a '
  ' sentry

where double-quoted "\n" comes through literally as desired,
while single-quoted '\n' comes through as quote-newline-quote.
Writing string "\n" instead of character '\n' is pedantically
annoying, but acceptable.

I don't mind following a bunch of restrictive rules if I know what
they are. And I can probably enforce them in 'test_coding_rules.cpp'
without making that program too slow.

>  Anyhow, I still don't think the resulting documentation can be described
> as being "nice" but now it's at least pretty complete.

Details are very incomplete, and there's no top-level documentation,
but aside from that what shortcomings do you see?