[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [lmi] doxygen
Re: [lmi] doxygen
Wed, 31 Mar 2010 13:09:10 +0000
Thunderbird 220.127.116.11 (Windows/20100228)
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> 3. Set EXTRACT_ALL = YES in Doxyfile to generate documentation for
> VS> everything, documented or not.
> 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<> .
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
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  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:
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
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 '#':
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
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">
/// wxDateTime Model::DateOfBirth; // Same name.
/// which may be accessed by the same string:
/// Model["DateOfBirth"] // As above.
The generated documentation
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:
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  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
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
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
"\n" instead of '^' and '$' anchors and prepend a '
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?