My Namespace, Forwarding Header, and Sub-library Philosophy Post

From: Daryle Walker (darylew_at_[hidden])
Date: 2002-03-14 16:35:36

Due to a recent post that I responded to, I realized that no one knows what
grouping philosophy I like applying to various sub-libraries I work with.
Well, let's try to explain it:

For example, we'll start a talk-show sub-library.  To stop the sprawl of
headers in the top boost header directory, components for talk-shows will go
in a "talk_show" namespace (within the "boost" namespace).  To make the new
headers easy to find, the headers for stuff in the "talk_show" namespace
will go into the new "BOOST_ROOT/boost/talk_show" directory.

Forward declarations, like <iosfwd>, make some applications of a class
easier.  We could make the forward declaration header
<boost/talk_show/fwd.hpp>, but I like <boost/talk_show_fwd.hpp> better
because I don't like a lot of headers with the short name "fwd.hpp".  This
header has forward declarations of classes, structures, and class templates
of all the public types in that sub-library's main headers.  Any defaults
for class template parameters should be mentioned here, which may require
#including another forwarding declaration header to get the default names.
Typedef-s of the specific versions of the class templates go here too.
However, full class/struct definitions, full class template definitions,
enum definitions, and function or function template declarations or
definitions do _not_ go in the forward declaration header.

Each of the main headers in the "talk_show" namespace should #include the
forward declaration header to enforce consistency.  If you used a forward
declaration of a template parameter default, you should #include the header
that fully declares that default.

Note that the previous two paragraphs imply that every time a new component
is added to a sub-library, any other component in that sub-library that you
use will get marked with a dependency recompile when you upgrade your Boost
installation.  Deal.  (I know you could avoid the problem by making a
forward declaration header for each sub-library component, but that would
result in a _lot_ of little FD-headers.  I'd rather take advantage of
grouping.)

The sub-library's extra files would be in "BOOST_ROOT/libs/talk_show".  It
would have the "doc", "test", "example", and possibly "src" subdirectories.
All the components will share those subdirectories.  The "doc" subdirectory
will have an "index.html" that lists the FD-header and all the main
component headers.  The main component headers listings will have links to
each component's HTML documentation in the same subdirectory.

Extra notes:
1.  A FD-header may have to #include <boost/config.hpp>.
2.  A major example of [1] would be when some of the components don't work
on some compilers.
3.  I may have forgotten stuff, but hopefully your comments and/or flames
will remind me.
4.  I'm trying to make the (new) I/O sub-library like this.  I've also tried
to make the math and integer sub-libraries approach this.

-- 
Daryle Walker
Mac, Internet, and Video Game Junkie
darylew AT mac DOT com