Re[2]: [lmi] doxygen

[Vadim Zeitlin]

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

 So while it has its drawbacks, namely:

- Much longer doxygen running time (almost 3 minutes here) which is not
  very important probably. 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 :-)

- The output now includes really everything, including the kitchen sink.
  This is more important but unarguably still better than not including the
  documented functions, of course.

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

 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
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'
test_coding_rules.cpp:370: Warning: explicit link request to 'include' could 
not be resolved
value_cast_test.cpp:468: Warning: Found unknown command `\1'
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

 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.
Maybe we could use some workaround like "ASCII 1" or "^A" instead of \1?

 Anyhow, I still don't think the resulting documentation can be described
as being "nice" but now it's at least pretty complete. And worth having for
the inheritance and collaboration diagrams only IMHO. And the list of all
classes [3] also shows how few of them are documented...

 Regards,
VZ

[1] 
http://www.tt-solutions.com/vz/lmi/docs/numeric__io__cast_8hpp.html#aedf5681cfe1986e2630badc21895b6f4
[2] http://www.tt-solutions.com/vz/lmi/Doxyfile
[3] http://www.tt-solutions.com/vz/lmi/docs/annotated.html