Re: [boost] random and detail namespace

From: Jens Maurer (Jens.Maurer_at_[hidden])
Date: 2000-06-28 17:07:14

Beman Dawes wrote:
> Dave Abrahams wrote:
>  >I just happened to take a look at the docs for the random library,
>  >and the fact that we are documenting things we're putting in the
>  >detail namespace hit me like a cold slap in the face ;\
>  >
>  >I thought detail was supposed to be reserved for implementation
>  >details of no interest to users...?
> 
> That was my understanding, too.  Jens?

As Matthias Troyer already pointed out, there are basically two levels
of users for the random library.  The generator definitions and
namespace placement reflects this:

 (1) Simple users which use one of the typedef's in namespace boost.
For these, the templates in namespace boost::detail are just that,
details.
 (1a) Users which still only use one of the typedef's in namespace
boost, but know enough of their (e.g. simulation) problem domain
that they want to avoid/prefer certain families of generators, for
example all linear congruential ones or all with a certain
parameterization.
 (2) Users with externally provided extensive background knowledge
which create their own generator parameterizations based on the
templates in namespace boost::detail.

For types (1a) and (2), it is important to document what is
currently in namespace boost::detail.  I'm willing to move
the documentation and/or the implementation namespace elsewhere,
though.  Note that for user type (1a), a relationship between
the typedef and the template documentation is required. This
relationship is currently established by text adjacency in the
documentation.

Howard Hinnant suggested a namespace random within namespace boost
where all definitions reside, possibly nested in deeper namespaces.
A "using namespace random" within namespace boost complements
the setup.  However, Beman said in a private e-mail that he
doesn't like that setup, although we have a precedent in
cast.hpp.

All things considered, it might be a good idea to move the
generator template definitions from namespace boost::detail into
namespace boost::random without a "using namespace random" in
namespace boost and adjust the documentation accordingly.
Other things, including the typdef's intended for user type (1)
and (1a) will remain where they are (i.e. namespace boost).

Comments?

Jens Maurer