Smart_ptr docs (was Re: [boost] scoped_ptr vs auto_ptr)

From: Ed Brey (brey_at_[hidden])
Date: 2001-04-09 08:11:42

From: "Beman Dawes" <bdawes_at_[hidden]>
> The primary reason to use scoped_ptr rather than auto_ptr is to let
readers
> of your code know that you intend "resource acquisition is
initialization"
> to be applied only for the current scope, and have no intent to
transfer
> ownership.
>
> A (very) secondary reason to use scoped_ptr is to prevent a later
> maintenance programmer from adding a function that actually transfers
> ownership by returning the auto_ptr (because the maintenance
programmer saw
> auto_ptr, and assumed ownership could safely be transferred.)
>
> Think of bool vs int.  We all know that under the covers bool is
usually
> just an int.  Indeed, some argued against including bool in the
standard
> because of that.  But by coding bool rather than int, you tell your
readers
> what your intent is.  Same with scoped_ptr - you are signalling
intent.

Excellent description.  Can you put that in the scoped_ptr docs?

Regarding the deletion protection involving an out-of-line destructor in
scoped_ptr, the following line in the docs will have to change:
"Because scoped_ptr is so simple, in its usual implementation every
operation is as fast as a built-in pointer and has no more space
overhead that a built-in pointer."

Losing this equivalency is a shame, although I do like being able to
point to incomplete types and its subsequent reduction in header
dependency.  If only there were a way to get the best of both worlds.
:-(  As a side opinion, I definitely don't think it would be worth
giving up the equivalency just to detect programmer-shorted-to-ground
errors that most compilers warn about anyway.

On another documentation topic, when peeking through the docs, I noticed
this like for scoped_arary:
"A heavier duty alternative to a scoped_array is a scoped_ptr to a C++
Standard Library vector."

While technically accurate, I wonder if this may mislead new users.
Most of the time, the vector alone is adequate; the scoped_ptr is only
necessary if, when using the scoped_array, the user was distinguishing
between a null pointer and an allocated 0-length array.