Re: [boost] [boostbook] doxygen docs for enums

From: Doug Gregor (dgregor_at_[hidden])
Date: 2004-09-27 10:02:18

On Sep 27, 2004, at 3:50 AM, Angus Leeming wrote:

> Next question ;-)
>
> I find that boostbook can handle doxygen docs for classes and for  
> functions
> but it ignores enums totally. That's both enums nested in classes and
> global enums. Any chance of getting it to add glob_flags.html to the  
> list
> below?

It does handle enums, although admittedly not that well. See, e.g.,

    
http://www.boost.org/regression-logs/cs-win32_metacomm/doc/html/ 
date_time.doxy.html

> Writing globbing.user_guide.html for section(globbing.user_guide)
> Writing bad_glob.html for refentry(bad_glob)
> Writing glob_iterator.html for refentry(glob_iterator)
> Writing glob_predicate.html for refentry(glob_predicate)
> Writing glob_traits.html for refentry(glob_traits)
> Writing glob.html for refentry(glob)
> Writing globbing.reference.html for section(globbing.reference)
> Writing globbing.history_and_acknowledgements.html for
> section(globbing.history_and_acknowledgements)
> Writing index.html for chapter(globbing)
> Writing HTML.manifest
>
> namespace boost {
>
> /** @brief The boost::glob function accepts a @c glob_flags
>  *  argument made up of a bitwise OR of zero or more of the
>  *  following symbolic constants.
>  */
> enum glob_flags {
>     /** The vanilla, POSIX glob behaviour. */
>     glob_basic = 0,
>     /** Do not sort the returned pathnames. */
>     glob_nosort = (1 << 0),
>     /** If no pattern matches, return the original pattern. */
>     glob_nocheck = (1 << 1),
>     /** Characters (including meta chars) cannot be quoted by  
> backslashes.
> */
>     glob_noescape = (1 << 2),
>     /** csh-style brace expressions {foo,bar} are expanded.
>      *  The glob will match either alternative.
>      */
>     glob_brace = (1 << 3),
>     /** Only directories are matched. */
>     glob_onlydir = (1 << 4)
> };
>
> } // namespace boost

Since this only has a brief comment (and the documentation on the enum  
values isn't included; that's a known issue), BoostBook actually places  
the description of the enum in a comment in the summary. I'm not sure  
if this is really a good idea, but it does reduce the size of the  
documentation a bit. If you want to always create a separate page for  
enums, set the XSL parameter boost.compact.enum to 0.

        Doug