Re: [boost] [smart_ptr] documentation

From: Peter Dimov (pdimov_at_[hidden])
Date: 2008-04-26 08:58:43

Daniel Frey:
> On Thu, 2008-04-24 at 23:23 -0400, Frank Mori Hess wrote:
>> On Thursday 24 April 2008 21:22, Daniel Frey wrote:
>> > On Wed, 2008-04-23 at 23:20 +0200, Daniel Frey wrote:
>> > > Peter, shall I write a patch for the documentation for
>> > > get_shared_count() and the new ctors? Or would you like to take care
>> > > of that?
>> >
>> > I prepared a patch for the documentation. While doing that, I noticed
>> > that the current ctor is a template ctor, which it should not be. Is:
>>
>> What's the point of documenting an unspecified reference counter type?
>> Following the interface specified by the docs, the only thing you can do
>> with get_shared_count() is pass its return value directly to the
>> constructor that takes a shared_count.  That adds nothing over the
>> aliasing constructor.  You can't store the return value in a 
>> shared_count,
>> because it's an unspecified type.

I agree with Frank that the "unspecified-type" documentation isn't very 
useful. The exact properties of the type are important (and would also 
affect the spec of ~shared_ptr and use_count). For example,

shared_ptr<X> px( new X );
weak_ptr<X> wp( px );
auto v = px.get_shared_count();
px.reset(); // does ~X run here?
wp.use_count(); // 0 or 1?

With v being an "unspecified type", you can't tell.

So... I'd rather not document the additional constructor and 
get_shared_count.

> Peter suggested to call it get_shared_count() instead of
> _internal_shared_count(), so I figured that this is going to be a
> documented public interface.

I've never explained my naming convention, but I see you figured it out in 
the later posts; _internal_* represents a member that is logically private, 
but is kept public to avoid compiler bugs with template friends. It can go 
away at any time, even in a point release (in theory). We want 
get_shared_count to be supported and stable, but undocumented because it 
relies on detail::shared_count, which is in itself undocumented. (Actually 
the supported part implies a test, which we don't have, but still.)