Re: [boost] Coding guidelines - function interface documentation

From: Jeremy Siek (jsiek_at_[hidden])
Date: 2001-07-10 16:15:00

On Tue, 10 Jul 2001, Beman Dawes wrote:
> Here is a reformulation:
>
> 7.3 All function interfaces must be documented, except for functions with
> obvious semantics, such copy constructors, operator overloads such as
> copy-assignment and dereference, and destructors. Even these functions must
> be documented if their semantics are in any way unusual.

So what are the "usual" semantics :) I think we mean deep copy semantics,
but that should be made explicit. It might be worth formalizing this to
some extent, i.e., that a copy of an object must be equivalent to the
original object in some sense. For example, if the objects have an
operator== then equivalent means

T b(a);
assert(a == b);
assert(b != c);
a = c;
assert(a != b);
assert(a == c);

Cheers,
Jeremy

----------------------------------------------------------------------
 Jeremy Siek                        www: http://www.lsc.nd.edu/~jsiek/
 Ph.D. Candidate, IU B'ton          email: jsiek_at_[hidden]
 Summer Manager, AT&T Research      phone: [phone]
----------------------------------------------------------------------