Re: [Boost-users] [range] questions about documentation and usage

Subject: Re: [Boost-users] [range] questions about documentation and usage
From: Vicente J. Botet Escriba (vicente.botet_at_[hidden])
Date: 2012-11-02 13:48:35

Le 02/11/12 17:54, Robert Ramey a écrit :
> Thorsten Ottosen wrote:
>> On 02-11-2012 07:11, Robert Ramey wrote:
>>> c) Another really annoying thing is that every thing is directly in
>>> the boost namespace.  This breaks the convention that library
>>> headers are in boost/<library name> and in the namespace
>>> boost::<library name>.  This creates a lot of opportunity for
>>> conflict.
>> Maybe so, but how would you change that without breaking code?
> No question that fixing this would break existing code.
>
> The real question is whether making this change would be worth
> breaking code.
>
> a) The breakage in users of range wouldn't be a big deal in my
> opinion.  Just rebuild the ap and fix the compilation errors.
This is not an option IMHO.
> b) Making such a change would be a fairly big job - not a tweak.
> Of course this is not a big concern to me as I wouldn't be doing
> the job.
I agree that while possible, this will take a lot of time.
>
> Here are a few miscelaneous personal observations on the range library
>
> a)  To me, the range library/concept is not appreciated to the extent
> it should be.  I don't think that potential users appreciate the utility
> of being able to compose adaptors.  I think the documentation would
> benefit from more examples.
How do you know what potential users appreciate or not.
Almost any Boost library could improve its documentation I I think some 
of them are already doing it.
>
> b) The documentation is pretty regular - I like this.  But each
> page needs a small example to help clarify things.  See fusion
> library for an example.
>
> c) I'm not crazy about the '|' syntax - OK I'm out voted here
> but I don't have to use it so I don't have any real objection.
Here we agree ;-)
>
> d) When I've used the library - I've found that I've had to
> spelunk through the code to understand how to "make it
> work".  Of course now I don't recall the specific cases other
> than the one which motivated this post, but they are common.
> I believe that more examples and tests would smoke these out.
I'm sure that if you post here the specific example that was confusing, 
the authors will try to correct it.
>
> e) Somethings are not quite right - the thing that motivated this
> post is the confluence of containers and ranges.  There might
> be other things.
What do you mean?
> I believe that this library could have a big future but that it needs
> more work to "get it right".
I think Boost.Range is an excellent library and that a lot of people are 
already taking advantage of it.
> This raises the question of how such
> work should get done.  Of course this situation apply's to many
> libraries.
>
>
We agree again.

Robert, I understand that you would like to see a lot of Boost libraries 
improved but that you can not do too much as you have a lot of work 
maintaining your own library. This is the case for most of the Boost 
library authors.

Best,
Vicente