Re: [boost] Documenting non-copyable-ness

From: Peter Dimov (pdimov_at_[hidden])
Date: 2001-09-04 17:12:02

From: "Beman Dawes" <bdawes_at_[hidden]>
> At 09:46 AM 9/4/2001, Peter Dimov wrote:
>
>  >From: "Beman Dawes" <bdawes_at_[hidden]>
>  >> It seems to me that part of the point of boost::noncopyable is that
> using
>  >> it should eliminate the need to document noncopyable semantics.
>  >
>  >I really don't know how to interpret this sentence. Of course it doesn't
>  >eliminate the need to document the fact that a class is noncopyable. It
>  >simply replaces one form of documentation:
>  >
>  >Class X is not copyable and not assignable.
>  >
>  >with another:
>  >
>  >class X: private boost::noncopyable
>  >
>  >I'd be interested to hear your reasons for preferring the second form of
>  >documentation.
>
> The wording you gave for the first form isn't complete.  What do "not
> copyable" and "not assignable" mean?  Are they defined anywhere?  Unless
> there is some very formalistic way of saying it, people will get it
> wrong  more often that if just referencing existing wording that someone
> has labored over to make correct.

It's possible but not necessary to provide precise definitions for 'not
copyable' and 'not assignable'. This is documenting 'negative' properties of
a class. In general the 'negative' properties cannot be enumerated fully (X
is not copyable, not assignable, not a predicate, not an adaptable function
object, ...) so the assumption is that whatever is not explicitly documented
is not there.

So it's perfectly possible to just say that the class is not copyable and
leave it at that (in a non-normative note, if you will.)

> The second form is more precise.

True; too precise, in fact. It mandates a particular implementation.

> That being said, perhaps we should defined a concept, NonCopyable, which
> gives a precise definition.  Then all that documentation would have to do
> is  say:
>
>    Class X meets the NonCopyable requirements.

Or, alternatively, "Class X does not meet the Copyable requirements."

--
Peter Dimov
Multi Media Ltd.