Re: [boost] [lib maintainers] Pleaseidentifyheadersinboost-root/boost

From: Joel de Guzman (joel_at_[hidden])
Date: 2007-11-18 18:48:39

Robert Ramey wrote:
> Joel de Guzman wrote:
> 
>> No, of course not. But was has boost/shared_ptr got to do with this?
> 
> wow - this is the iconic example of a violation of "standard practice"

Why are you saying that while insisting that there's no "standard
practice"?

> The file is implemented in boost/shared_ptr.hpp and shared_ptr
> class is to be found in namespace boost.  This is not what
> one would expect to find given that the documentation is
> smart_pointers ...

>> Yes, because boost/detail is not public API and the
>> stuff there is implementation detail.
> 
> Hmm - and implementation details shouldn't be documented?
> shouldn't be tested? If they're in a common area it seems
> that they are meant to be used by more than one library -
> and indeed they are. lightweight test others come to mind.
> 
> Its even worse.  Someone uses an "implementation detail"
> from this public area. and the author decides to make
> an interface breaking change.  This breaks a lot of stuff
> and the author says - what's the problem? its and implemenation
> detail.

I am not saying that. But this is irrelevant to the matter
at hand.

> Another case of ill defined "standard practice" creating problems.

Perhaps, but complain/object if you will in another thread.
This is irrelevant to what I am objecting to.

>> If a particular utility is useful for many libraries, then one of
>> the libraries can host it prior to it getting reviewed independently
>> and becoming a full-fledged boost citizen. That's the policy that
>> we've been following with the synergy between xpressive and spirit,
> 
> I faced exactly that same issue with headers such as static_warning.hpp
> There was already a header in boost/static_assert.hpp.  I thought
> (and still think) that logical place for static_warning.hpp was in that
> same directory.  I considered the possibility of placing it in

If everyone thinks the way you do, then we're in trouble.
Imagine hundreds of header files in the root directory and
thousands of components in the boost namespace. Project that
with the rate boost is growing! Man!

> boost/serialization/static_warning.hpp but at the time I thought
> I might have to change it later to boost/static_warning.hpp sometime
> in the near future and I wanted to avoid an interface breaking change.

Wrong decision! It would be the other way around.

>> for example. Case in point: fusion, proto, multi_pass, and many more
>> smaller utilities and stuff. fusion was hosted by spirit before it
>> was reviewed and was used by xpressive even before spirit did. Now
>> that fusion passed the boost review, it has become a full-fledged
>> boost citizen.
> 
> hmmm - I looked for it in boost on the trunk and 1.34 and didn't
> find either documentation for it nor code.  I don't doubt its in
> there somewhere but I can't find it.  Wouldn't "standard
> practice" suggest that I look in boost/utility or perhaps
> boost/iterators ? Hmmm has is been separately reviewed.
> 
> All these examples demonstrate that there really is
> no defined "standard practice" and never has been.

What documentation are you looking for? Fusion: it's in the main
libraries.html, proto: it's in xpressive (its host) multi_pass:
it's in spirit (its host). Can't see the pattern? It's obvious.

Regards,
-- 
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net