Boost logo

Boost :

From: David Abrahams (david.abrahams_at_[hidden])
Date: 2001-07-10 22:23:35

----- Original Message -----
From: "Beman Dawes" <bdawes_at_[hidden]>

I will give one example, however, of code written by
> you:
> template <class T>
> T next(T x) { return ++x; }
> Does this really need anything more?

Not in the code, but in the html, certainly.
However I admit I'd be tempted to leave that undocumented if it were an
implementation detail.

> >> * Effects: the actions performed by the function, especially
> >side-effects.
> >> Postconditions: the observable results established by the function.
> >
> >The issue of side-effects gets very interesting. I've recently been
> >emailing
> >with Scott Meyers who is having a hard time putting the effects of
> >functions
> >(say, those giving the strong exception-safety guarantee) in simple and
> >precise terms. I don't blame him. The difficulty occurs when a function
> >calls back into client code (e.g. when the client supplies a template
> >parameter, a derived class instance overriding a virtual function, or a
> >function pointer). To be really precise about this, you have to specify
> the
> >assumptions that the library makes about which client operations undo
> which
> >other ones (e.g. construction <=> destruction).
> Yes, agreed. But I'm not sure the guidelines are the right place for
> into details of "how to describe various common and uncommon side

If you tell people they should document the effects, you ought to say what
you mean.

> >> Also gives notice if the
> >> function provides anything other than the strong exception-safety
> >> guarantee.
> >
> >I could have sworn I changed that! I strongly believe the default
> guarantee
> >should be the basic guarantee.
> Maybe I was working with an older version. I thought it was current,
> though.

No, somehow my changes got lost.

> >> * Complexity: the time and/or space complexity of the function.
> >
> >I think there are domains in which this may be irrelevant, or left as
> QOI.
> >For example, we don't document the complexity of the iostreams
> Again, I just copied the standard. For Boost, and many libraries,
> complexity should only be specified when the effort of doing so (with its
> implied constraint on implementors) is sufficiently offset by the

Great. Would you like to submit updated proposed changes?


Boost list run by bdawes at, gregod at, cpdaniel at, john at