[boost] Re: Re: Re: Re: Re: [iostreams] Major interace changesplanned--comments requested

From: Jonathan Turkanis (technews_at_[hidden])
Date: 2005-03-10 19:32:46

Rob Stewart wrote:
>> From: "Jonathan Turkanis":
>> Rob Stewart wrote:
>>> From: "Jonathan Turkanis":

>>>> Yes, I was hoping to limit the interface to a single conversion
>>>> operator. I'd hate to see someone just learning the library look up
>>>> get() in the reference section, click on the return type and be
>>>> confronted with a monstrous synopsis. Could I present a "fictional"
>>>> synopsis of basic_character, which doesn't show all the overloads,
>>>> and include a note explaining the problem?
>>>
>>> What's fictional?.  The operators to which you refer would not be
>>> implemented as members,
>>
>> They might be friends implemented in-class.
>
> Sure, but they aren't strictly part of basic_character's
> interface so they don't have to be in the synopsis for the
> class.  Their being implemented as friends in the definition is
> an implementation detail that doesn't matter for documentation
> purposes.
>
> Thus, I wouldn't call the result of their omission a fictional
> synopsis.  Indeed, the meaning of "synopsis" means you can elide
> details.

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.

Jonathan