Re: [boost] [Range] No Reply?

From: David Abrahams (dave_at_[hidden])
Date: 2005-07-13 13:53:48

Thorsten Ottosen <nesotto_at_[hidden]> writes:

>>
>>> One should be able to look at a concept definition and understand
>>> which types will model that concept.
>
>  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.

>> I also said:
>>
>>> |   and the default behavior of boost::begin needs to be documented.
>>>
>>> it's documented in another document. I provided linke to in in the
>>> CVS version some time ago after you requrested it.
>>
>> 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.
>
> It's in the main cvs....how do I post a link to that?
>
> I usually keep a shortcut to the main cvs documentation.

Go to the boost web page. Follow the link in the left column to CVS.
There will be a link to CVSWeb.  Browse.

>>> 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.  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).

>>> Is it so hard to grasp?
>>
>> It is easy to infer what you mean, if you're very familiar with the
>> new iterator concepts.  It's also very easy to misinterpret if you're
>> not, because swappable iterator is a counterintuitive name.

Whatever you think of the rest, this is still valid and important.

>> More importantly, as I suggested, there is no need to name these
>> concepts (because you can just say "Requires: iterator<R>::type is a
>> model of RandomAccessTraversalIterator," or whatever),
>
> that is not very elegant IMO.
>
>> especially not before they have been shown to be useful in
>> specifying algorithms.
>
> their usefulness should be evident from the fact that you can make code
> self-documenting. it is much more elegant to
> have a meanningful name of a template parameter than to call the parameter T
> and then specify in comments that T is so and so.

Okay, I won't argue this one any further.

>>> 3. Implementation of concepts.
>>>
>>> A type conforms to a concept, so ok, you can't implement it. Maybe
>>> a renaming to "Implementations of types that concorm to Range
>>> concepts". ?
>>
>> 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.

I'm not just saying "go with the title you just suggested" because
your concept definitions still don't match any of the types you're
claiming conform.  Also, you're not really going to discuss the
implementation of std::vector here, though it is one of those types.
So I claim you don't really know what you want to say yet.  Make your
concept definitions accurate and complete, then consider what
information is missing.

>>> 4. links from concepts to implementation.
>>
>> I'm not sure what you're referring to.
>>
>>>    I remember I put some links when you asked for it. It should be
>>>    in the cvs code.
>
> ... in the cvs docs for the range library.

Where in the docs?

>>> 5. containers and iterators. It should be explained in the introduction
>>>  that pairs and containers "just works".
>>
>> That is insufficient.  The concept requirements have to be correct.
>>
>> And by the way, if you mean
>>
>>   "This library therefore provides the means to adapt standard-like
>>   containers, null terminated strings, std::pairs of iterators, and
>>   raw arrays (and more), such that the same generic code can work
>>   with them all."
>>
>> 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.

>> Also, IIUC, this and other mentions of null terminated strings need
>> to be removed now.
>
> yes, when I get the time or when somebody volunteers (1.33 is out of the 
> question).

If the code has changed, you have to change the docs before 1.33.
Otherwise, you have to do the change after 1.33.  I assumed that the
former was the case.

> Anyway, once I can get a chance to update from the cvs, I can tweak the 
> docs.
> (vs checkout: [15:53:38] waiting for agurtovoy's lock in 
> /cvsroot/boost/boost/bo
> st/test/utils/iterator)
>
> I don't have the feeling that the range docs are totally
> inappropriate, they could probably be better, but I wonder if it is
> worth our effort to spend days on them; our time could probably be
> better spend.

Boost documentation is easily as important as Boost code; it is
absolutely worth effort to spend days on it.  The quality of our
documentation (or lack thereof, in places) is becoming a serious
barrier to adoption (yes, I have empirical data to back this claim
up).  This stuff isn't easy; I have been writing the Parameter library
tutorial for about a week now.

As for whether these docs are "totally inappropriate," that's a bigger
value judgement than I'm willing to make.  However, they do have an
inappropriate level of completeness, rigor, and IMO understandability.

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