Re: [boost] Documenting non-copyable-ness (was: Re: Review: Boost.Threads)

From: Beman Dawes (bdawes_at_[hidden])
Date: 2001-09-04 08:07:50

At 01:22 PM 9/2/2001, Daryle Walker wrote:
 >on 9/1/01 8:17 PM, Bill Kempf at williamkempf_at_[hidden] wrote:
 >
 >> --- In boost_at_y..., "Peter Dimov" <pdimov_at_m...> wrote:
 >>> From: "William Kempf" <williamkempf_at_h...>
 >>>> From: "Peter Dimov" <pdimov_at_m...>
 >[SNIP]
 >>>>> The reference for many classes indicates that they derive from
 >>>>> boost::noncopyable. This implies, AFAICS, that a C-style cast to
 >>>>> boost::noncopyable* works. If retained, all such derivations need an
 >>>>> 'exposition-only' comment.
 >>>>
 >>>> They indicate private derivation, so the cast isn't valid.  So I'm 
not
 >sure
 >>>> the comment is needed, but I'm happy to add it.
 >>>
 >>> The C-style cast is, unfortunately, valid, even when the base class is
 >>> inaccessible. (5.4/7)
 >>
 >> Hmmm... ugly.  Can't say as I understand the reasoning for this.  In 
any
 >> event, the whole point of boost::noncopyable is to be used in private
 >> derivation in this manner, so I wouldn't expect much confusion with 
things
 >as
 >> they are now.  I will, however, add the comment.
 >[TRUNCATE]
 >
 >I haven't looked at the Threads library yet.  If you want to say that a
 >class is non-copyable in the documentation, then say that directly 
instead
 >of saying that the class derives from boost::noncopyable.  Use of
 >boost::noncopyable is an implementation detail, and mentioning it may 
make
 >some users try to take advantage of that inheritance.

See below.

 >Also, just saying that a class inherits from boost::noncopyable assumes
 >that
 >the user fully knows about Boost culture, at least about the
 >boost::noncopyable class.  New users would have no idea what that
 >inheritance implies unless they look up boost::noncopyable.

Uses of boost::noncopyable in Boost.Threads are hyperlinked to the 
noncopyable docs, so it really isn't a big deal to look at them.

But your other point does need to be addressed somehow.

It seems to me that part of the point of boost::noncopyable is that using 
it should eliminate the need to document noncopyable semantics.

So I'd like to see the question resolved by adding something to the 
boost::noncopyable documentation.  How about:

   Note:  The intended use for class noncopyable is to document and
   enforce noncopyable semantics.  The fact that this is
   accomplished via inheritance is an artifact that should not be
   depended upon by such perversities as casting to a pointer to
   noncopyable.

Comments?

--Beman