On Sun, 16 May 2010 03:06:07 -0700, Neil Groves <neil@grovescomputing.com> wrote:
I have acknowledged on this mailing list that a tutorial would make the Boost.Range documentation better. My schedule only just allowed a good, correct implementation with reference documentation for 1.43. Delaying for another release to fit in a tutorial would not have been the right decision. I apologise for the steeper than optimal learning curve.
No problem. Let me clarify that I am approaching the documentation/library from three perspectives: as an individual programmer, as an employee of company X, and as a supervisor with technological decision making responsibilities. From a an individual programmer's perspective, I can figure out how to use the library from the documentation, and if I find the syntax a little funny, I can live with that, same goes for the naming convention. But it's mostly from an employee's perspective and a supervisor's perspective that I am approaching this. Why? Because I think that Boost can make my life easier at work, and I would like to be able to use it. And the only way I would be able to use it would be to sell it to my boss and my peers. On technical grounds, it's a pretty easy sell. On usability, it's harder. What's a crucial factor in making usability easier, the documentation. Hence my comments/criticisms/suggestions on it (with no guarantee that any of it is actually valid, but, which is given in good faith).
Of course if you wish to contribute to the tutorial that would be very welcome.
Let me see what I can come up with.
2) What exactly is the definition of Range? Is it any type that meets the requirements of any one of the following concepts: Single Pass Range Concept, Forward Range Concept, Bidirectional Range Concept, Random Access Range Concept?
I normally speak of a Range as something that models the SinglePassRangeConcept or above.
If so, can you explicitly and prominently declare that in the documentation? The documentation here: http://www.boost.org/doc/libs/1_43_0/libs/range/doc/html/range/concepts/over..., really beats around the bush. It describes some attributes of Range, but doesn't quite define it.
The above link is to an overview of the Range concept. From my perspective it therefore, by definition, does not fully describe the Range Concepts. Specific improvements or at an example improvement would be more applicable feedback. The technical explanations for each of the range concepts is provided here:
http://www.boost.org/doc/libs/1_43_0/libs/range/doc/html/range/concepts/sing... http://www.boost.org/doc/libs/1_43_0/libs/range/doc/html/range/concepts/forw... http://www.boost.org/doc/libs/1_43_0/libs/range/doc/html/range/concepts/bidi... http://www.boost.org/doc/libs/1_43_0/libs/range/doc/html/range/concepts/rand...
Specifically I would suggest putting the definition of 2) in the Overview. (I take from your response that that is indeed the definition of Range.)
3) Why is the library named Range when it seems that only iterator_range actually encompasses a range of iterators. Am I missing something here?
I don't understand this point. The library is called Range because it defines Range types, Range algorithms and Range adaptors. This has been one of the less controversial naming decisions.
Maybe if Range was defined early on I wouldn't have this question. The reason I bring it up is because the word Range, in the absence of any definition, immediately conjures up something along the lines of [x, y) or some variation thereof. But, from my reading of the documentation a range can be any stl container, an array, a std::string, a pair of iterators, etc... And when I see the word Range, the first thing that pops to mind isn't exactly a container or an array, I have an easier time associating iterator_range with Range.
4) Having both range_iterator and iterator_range is just confusing. Are you trying to purposefully make me dyslexic? ;)
I appreciate that this can be a little confusing but coming up with a better name for range_iterator is very tricky, and there is actually a formulaic naming convention applied to the metafunctions where range_ is prefixed to the type that is extracted by the metafunction. iterator_range is the most sensible name for a range of iterators. That is the rationale, and of course it is too late to be flexible on this issue. This was not listed as a concern by anyone during the review process IIRC.
No problem. I'm approaching this with no expectations on my part. My only goal is to raise usability flags where I think there exists some.
5) Put "Notice that the above functions should always be called with qualification (boost::) to prevent unintended Argument Dependent Lookup (ADL)." prominently at the *top* of the following document, preferably with some sort of advisory icon.
http://www.boost.org/doc/libs/1_43_0/libs/range/doc/html/range/reference/con...
No! I respectfully disagree that it would be an improvement. Accidental ADL lookup for non-member functions is a general C++ issue, the only reason for the clarification requirement in the reference documentation is to ensure that it is understood that not using ADL will not prohibit the invocation of the extension mechanism. The extension mechanism is carefully designed to support extension even when the user is making fully qualified calls.
I probably should alter the documentation to clarify my intent however.
One of the hardest jobs of being a maintainer is saying 'No', but if I put to the top everything that each user considered the most important I would simply be shuffling the docs perpetually.
Just to clarify, as a general rule should the client always use boost:: ? If so, then let me explain my rationale. I'm working on a laptop with 1280 x 800 resolution. When I first land on the above website I see a table of functions that's cut off at "const_begin(x)". Okay, I mentally tell myself, it's just a table of functions and their explanations, good for reference, don't need it now, then press the "->" at the top of the page and keep reading on. Because the "->" appears on both the top of the page and the bottom, I'm not forced to scroll down to go to the next page, hence I miss whatever info is at the bottom. (This may very well be a bad habit on my part, but I don't think I'm the only one.) Even if I return to this page to lookup something, what I'll most likely be interested in can still be found without scrolling down enough to see that there exists non-tabular information at the bottom of the page.
This was carefully chosen language that actually resembles the documentation that the original author of any_iterator provides. A rant appears to be an inappropriate response.
Maybe I shouldn't have used the word rant; and hopefully I haven't dissuaded you from providing future insights/advice. Thanks, -Mostafa