I implemented an output optimization for enumerations in the XSL stylesheets,
but I would like additional opinions on its usefulness and whether I should
go ahead and implement it for other entities (e.g., functions).
Take, for instance, this declaration (+ Doxygen comment) from the Date-Time
library:
//! Enum for distinguishing parsing and formatting options
enum month_format_spec {month_as_integer, month_as_short_string,
month_as_long_string};
Originally, it would have been formatted in the synopsis like this:
enum month_format_spec;
Then month_format_spec would have its own <refentry> element, and generate its
own HTML page which the name "month_format_spec" would link to. On that
<refentry> page would be the full definition, along with the single-line
description. That takes up at least 20x the real estate that it did in the
actual source file.
The optimization I implemented was to look into the enum documentation when we
generate the synopsis. If the enum has no detailed description (e.g., no
<para> elements), then we put the full definition in the synopsis and the
purpose (if it exists) is put into a comment on the line immediately
preceeding the definition, like this:
// Enum for distinguishing parsing and formatting options.
enum month_format_spec { month_as_integer, month_as_short_string,
month_as_long_string };
Advantages of this approach:
1) Less generated text (especially important for dead-tree versions)
2) Less jumping around for only a little documentation
3) Faster processing (the DocBook XSL was spending up to half its time
grinding away at enum <refentry>'s in the Date-Time library documentation)
Disadvantages of this approach:
1) Synopses are no longer just synopses: they contain definitions that may
not be found elsewhere, and there will be links directly to them.
2) The C++ standard doesn't seem to ever do this (not that anything in there
is described in a single sentence...)
Should I do the same thing for functions? Should I back I these changes and
not use this approach?
Doug
-------------------------------------------------------
This SF.NET email is sponsored by:
SourceForge Enterprise Edition + IBM + LinuxWorld = Something 2 See!
http://www.vasoftware.com
_______________________________________________
Boost-docs mailing list
[EMAIL PROTECTED]
Unsubscribe and other administrative requests:
https://lists.sourceforge.net/lists/listinfo/boost-docs
