Re: [boost] [Range] No Reply?

From: David Abrahams (dave_at_[hidden])
Date: 2005-07-30 15:23:38

Thorsten Ottosen <nesotto_at_[hidden]> writes:

> David Abrahams <dave <at> boost-consulting.com> writes:
>
>> You snipped the following context
>> ----
>> >>> And then I asked that you post a link (both to the page with the
>> >>> boost::begin documentation and to the page in the main docs that links
>> >>> to it), but I have yet to see a reply.
>> ----
>> >
>> >> Go to the boost web page. Follow the link in the left column to CVS.
>> >> There will be a link to CVSWeb.  Browse.
>> >
>> > 
> http://cvs.sourceforge.net/viewcvs.py/*checkout*/boost/boost/libs/range/doc/rang
> e.html
>> 
>> I have looked at every instance of the word "begin" on that page and
>> there is NOWHERE a description of a library-provided function called
>> "begin."  I am talking about an entry that tells you:
>> 
>>     - what header it appears in
>>     - what its effects are
>>     - what it returns
>>     - what it throws
>>     etc.
>> 
>> Standard function documentation.  I'm having a hard time believing
>> that you really don't understand that this is required.
>
> right. I can provide cross links to the page which explains which
> header it is in.

Not sure what you mean there.

> The requiement should be that no function can throw.

_No_ function can throw?  I can't use this library.  I write lots of
functions that can throw.

> The return value is explained, perhaps a bit vague. But I'm not
> always sure having double information is a good idea. I mean, the
> intro on that page explains that a range encapsulates two
> iterators. 
> The docs for "begin(a)" then says that is called
> "Beginning of range". The semantics section then further says
> "Returns an iterator pointing to the first element in the
> Range.". Futhermore I give post-conditions and invariants.

That's nice, but your function's documentation should follow the
standard format.  Anything else makes it hard to read.  Per
http://www.boost.org/more/lib_guide.htm,

  #  For each function, as applicable, description, requirements
     (preconditions), effects, post-conditions, returns, and throws. 

You need to say what type it returns at the very least.

>> You snipped the following context
>> ----
>> >>>>> 2. swappable range:
>
>> > please just tell me how you would write it. I'll add your definition
>> > to the docs.
>> 
>> What you have now at
>> 
> http://cvs.sourceforge.net/viewcvs.py/*checkout*/boost/boost/libs/range/doc/rang
> e.html
>> seems fine.
>
> So you would just remove the range terminology page?

I'm sorry, which page are you talking about?  

>> But what you've written leads me to conclude that if I write
>> a model of Range, it will be unsupported.
>
> http://cvs.sourceforge.net/viewcvs.py/*checkout*/boost/boost/libs/range/doc/boos
> t_range.html#minimal_interface
>
> explains how to extend the lib. 

Yes, but that's in a different place.  You can't expect users to
understand your library if everything you write is an incomplete or
false statement when taken on its own, and can only be truly
understood by factoring in contradictory or amending information
somewhere else in your documentation!  Okay, it's not _everything_,
but we've seen that phenomenon over and over in this thread.

> It only lacks a discussion about providing these functions in
> namespace boost or in namespace Foo to take advantage of ADL.

Namespace boost won't work because of the difficulty of controlling
#include order.

>> > Even though the behavior of the primary templates 
>> 
>> What "primary templates?"  That term refers to a template definition
>> that is not an explicit or partial specialization.
>
> right.
>
> I don't see any conflict. I think this use is consistent with
> Daveed's book.

Well, if that's what you mean, what primary templates are you talking
about?  That's what I meant by 

        What "primary templates?"

>> > are exactly such that standard containers will be supported by
>> > default, 
>> 
>> What does "by default" mean?
>
> "out of the box"..."without adding extra oveloads"

Don't say they're supported, just say that each one models the range
concept corresponding to the category of its iterators.  Then you
describe the implementation of the library provided begin() and end()
functions that make it so. Yes, you need to do that.  If you don't,
nobody will know whether you're impelementing both begin() and end() as
c.begin() [range is always empty] or as rbegin() and rend() respectively
[range is the reverse of the container].

>> > the requirements 
>> 
>> Of what?
>
> of a range

Yes, I know that.  My questions are from the point-of-view of someone
who doesn't.

> It should be added. 
>
>> > are much lower than the standard container requirements. For
>> > example, the utility class iterator_range implements the minimal
>> > interface required to make the class 
>> 
>> Which class? [*I* can figure out what you mean, but the language here
>> is confusing.  Others will have a harder time]
>
> would "it" be better? 

Probably.

> And perhaps "a model of Forward Range" ?

either one is acceptable but I prefer the one you just suggested.

>> > a Forward Range.
>> >
>> > 
>> > Please also see Range concepts for more details.
>> 
>> At this point, if I didn't already understand this library from its
>> implementation, I would be lost, and a pointer to "Range concepts"
>> sure wouldn't help.
>
> Ok. What do you suggest then. Could you point to an introduction that
> captures all the good points?

The good points of what?

I'm not even sure what that first paragraph is supposed to accomplish.

(Obviously?) I feel that
http://boost-consulting.com/boost/libs/parameter/doc/html/reference.html
is a good example of reference documentation.

> Thanks for the feedback

You're welcome.

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