Thorsten Ottosen <nesotto@cs.aau.dk> 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