[boost] Re: Re: Re: Re: Re: Re: [iostreams] Major interacechangesplanned--comments requested

From: Jonathan Turkanis (technews_at_[hidden])
Date: 2005-03-11 13:51:10

Rob Stewart wrote:
> From: "Jonathan Turkanis" <technews_at_[hidden]>

>> I don't want to get distracted by the issue of whether the fact that
>> an operator is defined in a friend declaration can be considered an
>> implementation detail. My real question whether I can document the
>> basic_character interface, broadly conceived, as simpler than it
>> really is, and add a note explaining what's missing. I don't want a
>> simple library element to require a huge section of documentation.
>
> I'm not sure you got my point.  I don't think you can avoid
> documenting the full interface of basic_character, including the
> namespace scope operators.

But if they're defined as friends, there not technically namespace scope
operators. I guess I can define them at namespace scope just to avoid this
problem.

> However, you can provide a synopsis
> of the class that shows only the class members with a
> following section that discusses other functions that work with
> basic_character to give it a fuller interface.
>
> Thus, when clicking on the return type of get(), one sees a
> reasonably small class definition and discussion thereof.

Okay.

>  If one
> continues reading, one will learn about the namespace scope
> functions that augment that class' interface.  If one doesn't
> continue reading, one simply returns to the previous page
> thinking basic_character is a pretty simple class.

> Indeed, one might write code using only that rudimentary
> knowledge of basic_character and, following the lead of the
> existing filters and examples, take advantage of the wider
> interface and not even notice.  Eventually, such a one probably
> will wonder why certain expressions would work and will
> investigate the broader interface.

May be the reference section for basic_character can start out with some
examples.

Jonathan