[Boost-docs] [boost] Documenting reused concepts

Subject: [Boost-docs] [boost] Documenting reused concepts
From: Darren Garvey (lists.drrngrvy_at_[hidden])
Date: 2007-11-09 12:00:36

[cross-posted this to boost and boost-docs; I can't guess how many people
are interested in this.]

I'm looking but can't seem to find any comment on how to document reused
concepts, except for one very old, dead-end thread:
  http://lists.boost.org/Archives/boost/2002/09/35728.php

Basically I'm in a situation where I want to reuse concepts from a couple of
boost libraries so I obviously need to mention those concepts in my docs.
What I'm doing now is linking to the concept documentation in the relevant
library, which mostly works but I'm afraid it might confuse someone
unfamiliar with the other library.

The question is: how much concept documentation should lie outside
individual libraries?

I suppose there are some (many?) that are never going to be decoupled from
any one library, but I thought the nature of a 'concept'  - especially
looking at C++0x stuff - favours general ones. The ones in Boost.Thread (*
http://tinyurl.com/35tetq* - out of date, but still relevant) and Boost.Asio(
*http://tinyurl.com/2acksh* - see the RH column) seem to be laid out/named
like this.

I for one think it would be intuitive and helpful if there were a place for
library-agnostic concept documentation, somewhere. I get the impression
that's the way things are going anyway. Also, since they concepts are
usually documented anyway, *combining* the library-agnostic ones shouldn't
be too demanding a task (I'm offering). Deciding what concepts are
library-independent or even 'truly general' is another issue. I'm sure I can
already smell smoke over my anosmia. :-)

I was thinking a general concept interface, perhaps a C++0x-style definition
too (*http://tinyurl.com/2xhzpr*), plus links to the libraries that use them
and/or the types that implement them would be all that's needed.

Is there any interest in this? Any fundamental objections? Am I just
entering a world of pain?

Regards,
Darren

P.S. This would fit in nicely with the STL concept documentation effort that
Andrew Sutton's been working on (see *http://tinyurl.com/3x92du*).