Thorsten Ottosen <nesotto@cs.aau.dk> writes:
Citat David Abrahams <dave@boost-consulting.com>:
Hi Dave,
Thorsten,
there are important issues here that go to the suitability of this library for generic programming. I notice there was no answer on the list. It's crucial that you deal with these questions eventually, and IMO it should happen before the 1.33.0 release.
I'll see what I can do. My laptop was stolen two weeks ago, so its hard for me to do any real work.
Ouch! I'm sorry to hear that!
When is 1.33.0 going to be?
I think we're hoping to do a prerelease candidate this weekend or Monday.
Anyway, here's the issues:
I'm not sure that you quite "got" most of the concerns I raised.
1. change XXX to boost::XXX. ok, I don't see any problem with this. I could fix it monday.
-------------- If you already understood everything I'm writing in this section delimited by dashes, please just tell me so and I'll relax. I'm not asking for you to simply change XXX to boost::XXX everywhere. To quote from my original posting:
| 1. What does it take to get support for standard containers as ranges? | According to what I can see in the documentation, the standard | containers don't satisfy the range concepts. IOW, | | begin(v) | | isn't valid when v is a standard vector. | | From what I can tell from browsing the implementation, the | requirement should be: | | boost::begin(v)
The problem is that the Range concept requirements, as you specified them, are not satisfied by standard containers. Therefore the standard containers are not Ranges. Since it is a goal of the library that the standard containers be Ranges, you need to fix the way you've specified the concept requirements. And as I said later in the post:
One should be able to look at a concept definition and understand which types will model that concept. That concept definition may of course lead you to look at the implementation of other functions, but it has to let you get ahold of one end of the string, so you can follow it to its logical conclusion. That's why the concept definition should say that boost::begin(s) is a requirement... and of course it should link(**) to the documentation for boost::begin so the reader can find out what it takes to make that function work, and deduce that it works for standard containers.
-------------- 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.
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.
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. 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), especially not before they have been shown to be useful in specifying algorithms. There's no need to build a parallel and redundant concept hierachy. In fact, it's probably harmful to do so.
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? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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 code? I remember asking you to post some links. Or maybe you mean you fulfilled the request in (**) to put links in the documentation? Can you tell me where, on the boost-consulting CVS mirror, I can find that?
Do you want more links?
I can't know until I can see what you've already done.
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?" Also, IIUC, this and other mentions of null terminated strings need to be removed now. -- Dave Abrahams Boost Consulting www.boost-consulting.com
When is 1.33.0 going to be?
I think we're hoping to do a prerelease candidate this weekend or Monday.
rigth, so we can still change documents.
Anyway, here's the issues:
I'm not sure that you quite "got" most of the concerns I raised.
1. change XXX to boost::XXX. ok, I don't see any problem with this. I could fix it monday.
--------------
If you already understood everything I'm writing in this section delimited by dashes, please just tell me so and I'll relax.
I'm not asking for you to simply change XXX to boost::XXX everywhere.
ok.
And as I said later in the post:
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.
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.
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.
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. 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.
There's no need to build a parallel and redundant concept hierachy. In fact, it's probably harmful to do so.
how so?
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? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
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 ???
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). 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. best regards -Thorsten
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
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?
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
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.
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?
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?
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.
the former is the case.
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).
the boost documentation is in general good IMO.
This stuff isn't easy; I have been writing the Parameter library tutorial for about a week now.
looking forward to read that. best regards -Thorsten
Sorry it took me so long to reply. Among other things, I've been sick. Thorsten Ottosen <nesotto@cs.aau.dk> 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/...
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/... 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
David Abrahams <dave <at> boost-consulting.com> writes:
Sorry it took me so long to reply. Among other things, I've been sick.
No worries...good thing thing yuo're back.
Thorsten Ottosen <nesotto <at> cs.aau.dk> writes:
David Abrahams <dave <at> boost-consulting.com> writes: 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?!
right. I need to change the concept requierment. Thanks for spelling it out for me.
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. The requiement should be that no function 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.
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?
maybe it should just be called Synopsis & Reference?
Maybe. The change looks good. I think just "Reference" would be perfect actually.
Ok.
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.
that is an unfortunate vague language.
I assume you mean "can model Range."
yes.
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. It only lacks a discussion about providing these functions in namespace boost or in namespace Foo to take advantage of ADL.
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.
are exactly such that standard containers will be supported by default,
What does "by default" mean?
"out of the box"..."without adding extra oveloads"
the requirements
Of what?
of a range 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? And perhaps "a model of Forward Range" ?
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? Thanks for the feedback Thorsten
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
Thorsten Ottosen <nesotto@cs.aau.dk> writes:
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.
the former is the case.
Does everybody think it's okay to release 1.33 docs with the false promise that Boost.Range includes special null-terminated string support? That seems very wrong to me, and so avoidable! -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams writes:
Thorsten Ottosen <nesotto@cs.aau.dk> writes:
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.
the former is the case.
Does everybody think it's okay to release 1.33 docs with the false promise that Boost.Range includes special null-terminated string support? That seems very wrong to me, and so avoidable!
Seems very wrong to me as well, especially since the fix could be as easy as including a prominent one-sentence warning on the library's main page. -- Aleksey Gurtovoy MetaCommunications Engineering
Aleksey Gurtovoy <agurtovoy@meta-comm.com> writes:
David Abrahams writes:
Thorsten Ottosen <nesotto@cs.aau.dk> writes:
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.
the former is the case.
Does everybody think it's okay to release 1.33 docs with the false promise that Boost.Range includes special null-terminated string support? That seems very wrong to me, and so avoidable!
Seems very wrong to me as well, especially since the fix could be as easy as including a prominent one-sentence warning on the library's main page.
I'm a little confused now. According to what Thorsten wrote above, the code has changed so that null-terminated strings no longer get special treatment. However, according to what he wrote to me in private email, making the suggested change to the docs would make them inconsistent with the code. So I think he must've been confused above. IIUC he is planning to put a deprecation warning in the docs for 1.33.0 so that in 1.34.0 we can change the behavior. -- Dave Abrahams Boost Consulting www.boost-consulting.com
participants (3)
-
Aleksey Gurtovoy -
David Abrahams -
Thorsten Ottosen