Re: [boost] [serialization] Header Placement

From: Robert Ramey (ramey_at_[hidden])
Date: 2006-05-22 15:00:08

Hmm - if I knew everything I know when I started, I might have
done a lot of things differently.  I do remember the motivation
for some of decisions which I can state here which might or
might not be helpful.

David Abrahams wrote:
> The serialization library seems to blatantly violate Boost header
> placement conventions.
>
> 1. Normally detail namespaces are for implementation details that
>   should never be touched by a user of the library, but Serialization
>   puts several framework classes designed to be used by archive
>   authors inside of detail subnamespaces.

I made a distinction between archive authors - a small group and
archive users a much larger group.  I put those things of interest only to 
archive
users in detail namespace.  Even so, there are only a couple
of things there - abi stuff, and common implementations
I would expect archive authors to use without having to
alter or even look at.

> 2. Also, the top-level boost/ directory is supposed to be reserved for
>   non-implementation details, i.e. files with documented purposes
>   that expose the interfaces of accepted libraries, yet
>   boost/pfto.hpp is clearly an implementation detail of the
>   serialization library.  It is not a header I would bet any other
>   Boost library would use, but if I'm wrong about that, it should at
>   least be pushed into boost/detail, where common implementation
>   details live.

When I did that, I saw pfto.hpp as a general solution to addressing
the problem of compilers which fail to properly implement
partial function template ordering.  I had no way to forsee whether
or not others would find this useful, but I certainly didn't see it
as anything specific to serialization. I don't know if anyother boost
library uses this to address the problem,  I did find it necessary
to implement "dataflow iterators" in  a portable way.  So
its useful in other contexts aside from serialization.  I suppose I should 
have
documented it as a separate thing in "misc".

> The conundrum of item 2 is partly the from a mistaken organization.
> boost/archive/ and boost/serialization/ are segments of the same
> library, and they should have been organized as such.  An obvious
> organization would've been boost/serialization/archive and, e.g.,
> boost/serialization/streaming.  Then boost/pfto.hpp could've been
> boost/serialization/detail/pfto.hpp

We've been here before.  I went a lot of effort to maintain the
distinction between archive and serialization - "concepts" (uh oh)
and having that reflected in the namespaces used.
I realize that not everyone sees the value in the separation, but
I'm convinced that it has been invaluable in making the library
easier to build and maintain.

I could have make another layer

boost::
    ???::
        serialization
        archive

and sprinkled ???:: all over the place with no gain in clarity

The directory organization mirrors the namespaces which
seems quite natural to me.

It also wasn't clear to me that "serialization" wouldn't be
be eventually absorbed in something like a future system
implementing "reflection" or that "serializable" might
find its way into some sort of type_traits thing.  I
wanted the concept of a serializable type to stand
independent of the archive.  These things havn't
come to pass, but they were present in my mind
at the time.

> These unconventional moves are at best confusing for users and other
> maintainers.  The Boost source base is hard enough to control without
> library authors inventing their own new rules for organizing things.
> I realize that these problems can't be repaired all at once, but they
> should be fixed.

I think you're blowing this way out of proportion.

> I'd start by pushing boost/pfto.hpp into boost/detail, for example.

I can see the apeal of that - feel free.

Robert Ramey