Re: [boost] [RFC] Header/namespace policy draft

From: David Abrahams (dave_at_[hidden])
Date: 2007-12-02 23:10:34

on Sun Dec 02 2007, Joel de Guzman <joel-AT-boost-consulting.com> wrote:

> David Abrahams wrote:
>> on Sat Dec 01 2007, Joel de Guzman <joel-AT-boost-consulting.com> wrote:
>> 
>>> My opinion on this is to keep the boost/detail *solely* for
>>> core libraries use. For non-core libraries, it is always better
>>> to use boost/<library>/detail and boost::<library>::detail
>>> as many libraries are already doing. If they need to be used
>>> by other libraries, then my thinking is that they ought not to
>>> be in detail, but rather, hosted by a parent library, just
>>> like that suggested in the last item in the list of current
>>> "practices". Then, the natural place for its documentation is
>>> the host library (e.g. The proto docs are currently in xpressive,
>>> the pre-review of fusion was once in spirit).
>> 
>> That doesn't always work.  For example, I have a number of tiny
>> utilities in Boost.Python that I needed to re-use in Boost.Iterator.
>> Having Boost.Iterator depend on Boost Python would be totally
>> inappropriate, so after I got things working I moved these components
>> into boost/detail.  That's the way boost/detail ought to be used.
>> 
>> These components are tested and commented, but they are pretty
>> obscure, and making them into public Boost components would entail
>> writing rationales, tutorials, and formal interface documentation.  I
>> didn't have time for that, and almost nobody would have benefited from
>> it: adding more oddball components into the list at
>> http://boost.org/libs will only make it harder to find the useful
>> stuff.  
>
> My concern is that this policy does not seem to be scalable.
> What's to prevent someone from adding hundreds of small things
> (typedefs, enums, small classes, etc.) in boost detail? 

The policy does. It says you only do that when they are in fact needed
by multiple libraries.  And anyway, what's wrong with having hundreds
of small things in boost detail?

> You may
> say common sense will prevent people from doing so, 

I would say that too.

> but with a free for all addition into boost::detail, 

Who ever suggested a free-for-all?

> this is not a paranoid scenario in the future when Boost grows even
> bigger and a lot more things can go wrong, slipping from the common
> sense radar screen. Now, multiply that to hundreds of developers. To
> me, it will not be a pretty situation.

> I do not see Boost.Iterator having dependence on Boost.Python if the
> common components are segregated sufficiently in, say,
> boost/python/support.

You may not see it that way, but I do.  And I know most other people
will see it that way until they understand the very interesting
concept that libx/support isn't really part of libx.

http://lists.boost.org/Archives/boost/2004/05/65592.php
http://lists.boost.org/Archives/boost/2005/08/91483.php

> Fusion was once hosted by Spirit and xpressive used Fusion. That
> does not mean that xpressive had a dependency on spirit. It's just
> the location.

Was Fusion a component of Spirit, or was it not?  If it was, and
xpressive depended on it, then it depended on (a part of) Spirit.  One
library rarely depends on another library entirely, so this isn't any
different than depending on boost/type_traits/is_same.hpp.

> Anyway, if it's used by both Boost.Python and Boost.Iterator,
> I'd say that Boost.Iterator should be the host since it is a
> core library.

Now to play the devil's advocate: core as defined by whom?

>> Sometimes a really general and useful component will end up in
>> boost/detail (or <libraryname>/detail) because the author just
>> doesn't have time to do what it takes to make it a public part of
>> the Boost interface.  That's legitimate, too; this is a volunteer
>> effort, after all.  If someone wants it in the public interface
>> badly enough, he or she can take responsibility for getting it
>> there.  That's what ha
>

Yes.  Well IIRC that's what happened with boost/detail/value_init.hpp
but I could be mistaken.

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com