Re: Re: Writing Boost Documentation

From: Tom Becker (voidampersand_at_[hidden])
Date: 2002-02-04 22:19:15

On Mon, 4 Feb 2002 15:23:00 -0500, "David Abrahams" 
<david.abrahams_at_[hidden]> wrote:
>  > > > > ...and now for an experience report: I'm trying to use the
>  > > > > templates for documenting the next version of Boost.Python.
>  > > > > Looking at my index page, I can see right away that the
>  > > > > format is going to be good for small libraries of one or two
>  > > > > headers, but that for a project of the scale of Boost.Python,
>  > > > > a more hierarchical navigation structure will be needed.
>  > > > > Here's what I see now:
>  > > > >
>  > > > > Contents
>  > > > > Overview
>>  > > > Reference
>>  > > >     {{header}}
>>  > > >         Macros
>>  > > >             {{macro name}}
>>  > > >         Values
>>  > > >             {{value name}}
>>  > > >         Types
>>  > > >             {{type name}}
>>  > > >         Classes
>>  > > >             {{class name}}
>>  > > >         Functions
>>  > > >             {{function name}}
>>  > > >         Objects
>>  > > >             {{object name}}
>>  > > > Configuration Information
>  > > > > ...
>  > > > >
>  > > > > It would be great if we could have some alternate templates for
>  > > > > libraries like Boost.Python v2 or MPL which have approximately
>  > > > > one component per header.

>Boost.Python V2 is evolving into a framework, with high-level and
>lower-level components. I'd rather organize them according to their use and
>category. It seems as though I'll need at least one additional level of
>hierarchy to distinguish groups of headers.

For large libraries, how about using Bill's format for documenting 
each component (or set of small closely related components), and a 
different format to provide an overview of the components? That would 
give you the additional level of hierarchy, without making the file a 
lot larger. The top level file would have a different level of 
detail, so it probably should have a different format. Here's a 
possible format, that is based somewhat on Bill's format and somewhat 
on the top-level boost documentation:

Contents
Overview
     Usage
Components
     {{component name}}
     link to component document
Configuration Information
     Installing
     Building
     Testing

I'm not sure components is the best word to use, but it's what you 
mentioned, and it seemed better to me than sub-libraries.

If we can figure out a good format for documenting large libraries 
inside boost, boost is a large library too.

Regards,

   Tom

-- 
Tom Becker                      "Within C++, there is a much smaller and
<voidampersand_at_[hidden]>        cleaner language struggling to get out."
                                                       -- Bjarne Stroustrup