Re: [boost] [range] How to extend Boost.Range?

From: David Abrahams (dave_at_[hidden])
Date: 2005-09-13 15:13:31

Thorsten Ottosen <nesotto_at_[hidden]> writes:

> David Abrahams <dave <at> boost-consulting.com> writes:
>
>> 
>> "Eric Niebler" <eric <at> boost-consulting.com> writes:
>
>> > I put the using declaration in the requirement because without it, users 
>> > might rightly wonder how a type such as int[5] could fulfill this 
>> > particular requirement. 
>> 
>
>> So why not simply document that there exists in namespace
>> boost:
>> 
>>     template <class T, std::size_t N>
>>     T* begin(T(&x)[N])
>> 
>> with semantics
>> 
>>     return &x[0];
>> 
>> ??
>
> The reference docs state exactly what the functions returns.

Yes, but the presentation is unprecedented.  It's also a bit
confusing, because until you understand how to read the tables, each
function appears to have multiple return values.

Normally, the table format should be used for describing concept
requirements, and individual functions should be documented in the
usual way, e.g.:

     template <class T, std::size_t N>
     T* begin(T(&x)[N])

     Returns: &x[0]
     Complexity: Constant time

If you want to invent a new documentation style you need to make sure
to document the documentation style :)

> In the RC branch, I've added the following line:
>    
>    boost_range_begin(x) otherwise 

That only adds to the confusion when there's no conditional ("if ...")
present.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com