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

From: Rob Stewart (stewart_at_[hidden])
Date: 2005-03-11 12:25:03

From: "Jonathan Turkanis" <technews_at_[hidden]>
> 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.

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.  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.  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.

-- 
Rob Stewart                           stewart_at_[hidden]
Software Engineer                     http://www.sig.com
Susquehanna International Group, LLP  using std::disclaimer;