Re: [boost] The perfect tutorial example?

From: David Abrahams (dave_at_[hidden])
Date: 2005-07-10 09:35:16

David Abrahams <dave_at_[hidden]> writes:

> Douglas Gregor <doug.gregor_at_[hidden]> writes:
>
>
> Say, that doesn't correspond to what I see at
> http://www.boost-consulting.com/boost/libs/graph/doc/depth_first_search.html
> and furthermore I think that last "nontrivial default" is a type, not
> a value.  Can you clear this up?  Did you mean a different algorithm?

A note about the graph library named parameter doc format: it's almost
inscrutable, and it puts the elements in an order that doesn't
correspond to their relative emphasis.  For example:

  IN: vertex_index_map(VertexIndexMap i_map)

- You start with the I/O role of the parameter, and CAPITALIZE IT, no
  less!  That's the most visible thing on the line, and the word that
  lines up horizontally from parameter to parameter.  You should be
  showing the parameter name first, and probably in bold.  People get
  a very strong idea of the meaning of a parameter from its name, at
  least if the name is well-chosen.

- What I see above, after "IN," looks like a function declaration.

- Which is the name of the parameter, "vertex_index_map" or "i_map?"
  I'm guessing i_map is an internal name and could be dropped, and
  vertex_index_map is the name of the function (or member of
  bgl_named_params<>) that you call.

- Ooooh, now it all begins to be clear.  Still, it took me a long
  time, though.  I presume this will _need_ to be changed when you
  start using Boost.Parameter, since the primary interface won't have
  anything to do with functions.

- Anyone not using the named parameter interface still needs to read
  these descriptions to understand the defaults they get for the
  positional overloads, so they are forced to understand
  bgl_named_params in order to get started.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com