> 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)
Seems like a reasonable optimization to me.
> 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?
I don't feel as comfortable with this for functions, but if it becomes
a noop when a longer description is added I can't see how it would be
a problem.
Jeff
-------------------------------------------------------
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
