Re: [boost] [Range] No Reply?

From: David Abrahams (dave_at_[hidden])
Date: 2005-07-22 17:07:46

Sorry it took me so long to reply.  Among other things, I've been
sick.

Thorsten Ottosen <nesotto_at_[hidden]> writes:

> David Abrahams <dave <at> boost-consulting.com> writes:
>
>> >  It's not like I don't agree, it's just that it is already said in the
>> > introduction.
>> 
>> People will use this as reference docs.  Don't expect them to read
>> cover-to-cover.  They will jump to the concept definition, and that's
>> reasonable.
>
> right.
>
> so you propose an extra bullet like
>
> *Models*
>
> - all standard containers
> - std::pair<iterator,iterator> where iterator is an XXX iterator
> - builtin arrays
>
>
> for each concept?

Yes, that would be very helpful, but no, that's not what I'm asking
for.   It's not enough.  The concept definition that the
implementation relies upon is that

   boost::begin(v)

is valid, etc., not that

   begin(v)

is valid.  If you tell people the requirement is the latter, and then
you tell them that standard containers are models of Range, they 
say:

   You're lying.  There's no begin(v) for a std::vector v.

or they say:

   Okay, there must be a begin(v) for a std::vector v, since you tell
   me it's a model of the concept.  I'll write an algorithm that
   requires a Range argument, and then I'll use begin(v) on it.  Works
   great... until I pass a std::vector!  Okay, that's broken, but
   maybe I'll fix it by writing a begin overload in my own namespace.
   Now begin(v) is valid... it still doesn't work!  What is wrong?!

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/range.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.
You snipped the following context
----
>>>>> 2. swappable range:
>>>>>
>>>>> The page says: "Since ranges are characterized by a specific underlying iterator
>>>>> type, we get a type of range for each type of iterator."
>>>>>
>>>>> that's the definition. 
----
>>> >> Sorry, but that's not a definition of anything.
>> >
>> > The sentence says that each type of iterator induces a type of range.
>> 
>> It's still not a definition of anything. 
>
> <g>
>
>> Please try not to make this
>> so difficult for me.  Going back and forth like this takes a lot of
>> energy from both of us; we'd both be done sooner if you'd resist less
>> (or if I just gave up).
>
> 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/range.html
seems fine.
>> >> I don't know what the right title is first try to answer the question
>> >> I asked:
>> >>
>> >> You need to rename this page.  What is it really describing?
>> >>                               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>> 
>> So, what is the page really describing?  Please just try to nail down
>> in a few sentences, what you are trying to tell the user on this
>> page.  That will tell us what the right title is.
>
> It contains synopsis and from the synopsis you can jump to the
> definition of the function/metafunction in question. 
>
> maybe it should just be called Synopsis & Reference?
Maybe.  The change looks good.  I think just "Reference" would be
perfect actually.
>> >> then no, it doesn't make it clear that they "just work."  It claims
>> >> that the library gives me the *means* to make them "just work."  So
>> >> I'm left asking, "how do I do that?"
>> >
>> > have you read the introduction *and* its example ???
>> 
>> Do not expect users to read cover to cover.  Introductory and tutorial
>> material can be considered non-normative, and can leave out some
>> details if absolutely necessary, but the concept definitions are part
>> of the reference and the reference documentation needs to stand on its
>> own.
>
> yeah. would the "models" bullet help?
Yes, but as I described above, it's not enough.
The reference needs a lot of work:
> Overview
> 
> Four types of objects are currently supported by the library:
> 
>     * standard-like containers
>     * std::pair<iterator,iterator>
>     * null terminated strings (this includes char[],wchar_t[], char*, and wchar_t*)
>     * built-in arrays
You don't say what "supported" means.  I assume you mean "can model
Range."  But what you've written leads me to conclude that if I write
a model of Range, it will be unsupported.
> 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.
> are exactly such that standard containers will be supported by
> default, 
What does "by default" mean?
> the requirements 
Of what?
> 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]
> 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.
Gotta run now; I will try to comment on the rest of it soon.
-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com