Documentation, Etc.

It seems to me that the Boost.Graph documentation has gotten a little stale and needs a face-lift (i.e., rewrite to quickbook). There are also some older parts of the documentation that don't appear to align with current practice - especially those parts related to internal or bundled properties. If you read closely, you get the idea that bundled properties are the preferred technique, but they have yet to earn an entry into the table of contents.

(Jeremy: yes, it would be good to make the bundled properties more visible and better documented.)

Of course, the documentation isn't the only place where Boost.Graph doesn't align with the rest of Boost. For example, there is no boost::graph namespace. While this isn't exactly a tragedy for the ages, it would provide a clean separation from the rest of Boost. I am considering implementing my [un]directed_graphs in a boost::graph namespace.

(Jeremy: yes, I'm in favor of going with a boost::graph namespace. It turns out that back when the BGL was added to Boost we had not yet developed boost guidelines for namespace use.)

Another advantage of adding the boost::graph namespace is that it provides a mechansim for doing some other interesting things like reordering the parameters of common Boost.Graph function calls. One of my biggest complaints when I started learning the library was that the graph was always passed as the last argument in these functions. This doesn't really mesh well with the common "C-style" object-oriented approach where the type of the first parameter generally indicates the type to which said function would belong as a method. Is it really that big of a deal? I don't know... but it would be pretty easy to reorder parameters likes this (for example):

namespace boost { 
  namespace graph {
    template <class C>
    inline std::pair<typename C::edge_descriptor, bool>
    add_edge(boost::directed_graph_helper<C>& g, typename C::vertex_descriptor u, C::vertex_descriptor v)
    {
      return boost::add_edge(u, v, g);
    }
  }
}

Just a thought... There's probably some reason why this might break that I haven't thought of. And yes... that's what the signature of the add_edge() function actually looks like for directed graphs.

(Jeremy: I'm not a fan of changing the parameter ordering as that change would have to propagate throughout the BGL, and it would break lots of user code.)