Re: [boost] Coding guidelines - function interface documentation

From: Beman Dawes (bdawes_at_[hidden])
Date: 2001-07-11 12:45:38

At 11:23 PM 7/10/2001, David Abrahams wrote:
 >
 >----- 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.

Yes, I should have given an example which was an implementation detail.

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

OK, I'll try some additional wording.

 >> 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
 >benefits.
 >
 >Great. Would you like to submit updated proposed changes?

OK, I've sent proposed HTML to you via private email.

--Beman