Re: [boost] Re: Boost Documentation Template questions

From: David Abrahams (david.abrahams_at_[hidden])
Date: 2002-02-11 14:26:10

----- Original Message -----
From: "bill_kempf" <williamkempf_at_[hidden]>

> > 1. No provision for templates. Is it intended that class templates
> go in the
> > "Classes" section and that function templates go in the "functions"
> section?
>
> Yes.  This was the structure/design used by the standard.  If this
> doesn't work we can create more sections, or if all that's needed is
> to explicitly state this in the documentation I can make that
> change.  Which do you think is needed?

Mostly the latter, for now. Also, I'd like to know the purpose of "types".
Is that for unions and typedefs?

> > 2. No provision for concept definitions.
>
> In Boost.Threads I've just been using a general document page, and
> for that you can borrow the template for the Overview section.
> However, it would probably be beneficial to have a full template for
> these.  If you need a template quickly then could you create one and
> check it in?

I don't know where the stuff lives in CVS. If I'm about to start on a
template, I'll let you know. Otherwise, it's up to you.

> BTW, thanks for the reports.  They'll help in cleaning this stuff up
> before the next actual release, when those who might not be willing
> to live with the growing pains could simply give up on using the
> templates.

No prob. Here's the latest. I'm documenting some granular headers. It's
looking like this so far:

call.hpp
    Functions
        call
class.hpp
    Classes
        class_
class_fwd.hpp
    Classes
        class_
copy_const_reference.hpp
    Classes
        copy_const_reference
copy_non_const_reference.hpp
    Classes
        copy_non_const_reference
default_call_policies.hpp
    Classes
        default_call_policies
        default_result_converter

    ...

I've always been taught (and agreed) that an outline item should always have
more than one sub-item. In that light I'm not sure this approach is working
out so well. Remember that the standard documentation suits the standard
headers, which bring massive amounts of diverse code together.

Also, I'm starting to get really hungry for some automation. Just massageing
the templates into shape can be really tedious and error-prone.

-Dave