[boost] [graph] quickbook reference docs and formatting

Subject: [boost] [graph] quickbook reference docs and formatting
From: Andrew Sutton (andrew.n.sutton_at_[hidden])
Date: 2009-09-03 10:46:40

Jeremiah, Nick, others with opinions....

Two questions:

First, I need a second opinion on some formatting alternatives for the
quickbook docs w.r.t the documentation of member/non-member functions of the
graph classes.

These should be mostly buildable - there are some errors about missing
links, but they aren't fatal. Let me know if there are issues building them.
I got the doc toolchain working a while ago and I'm afraid to mess with it.
I may not have the same set up as everybody else. Hopefully I do.

The HTML docs give a flat listing with each function separated by a HR
element, which is effective (although not especially navigable). Other
lib**raries
(e.g., Boost.Filesystem) present a similar listing although without the HR's
to divide the content. I've tried putting these in a table to improve
readability, and it works a little but, but I don't have enough control over
the table to prevent auto-wrapping, which can break a function declaration
line in weird places.

So what's better: a flat listing or a table? Is there a third option?
Generating reference docs via Doxygen (like ProgramOptions) probably isn't a
viable solution since there's a lot of metaprogramming and atypical class
construction going on in the BGL.

Second, all of the reference docs for graph classes cite their associated
types via the graph_traits and property_map templates. For most of these
types, this strikes me as superfluous at best and slightly disingenuous at
worst. Traits classes are only required in a generic context, not when
working with a concrete type. If your graph class defines a nested type,
vertex_iterator, why not use it directly? I feel that the reference
documentation for data structures would be better served by focusing on the
specifics of the data structure, not its generic interfaces. That's what the
concepts are for. Thoughts?

Andrew Sutton
andrew.n.sutton_at_[hidden]