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