Re: [boost] using concepts in library documenation (was GIL - Generic Image Library Review - Begins October 5)

From: Jeff Garland (jeff_at_[hidden])
Date: 2006-10-07 13:25:52

Andy Little wrote:
> "David Abrahams" <dave_at_[hidden]> wrote in message 
> news:873ba0w7ck.fsf_at_pereiro.luannocracy.com...

>>> Now I shall sit back and watch the goalposts move as if by magic ...
>> Thought experiment #1: is there possible outcome here -- other than me
>> conceding that I "specifically told you" something I never said or
>> meant to say -- that would convince you the goalposts aren't being
>> moved?
>>
>> Thought experiment #2: what does someone who makes such a remark hope
>> to accomplish by it, and what does it _actually_ accomplish?
> 
> I don't think there is anything I want to say in response.

I tell you what it accomplishes for me -- it makes me want to put the person 
that writes this sort of hyperbole into the /dev/null filter.  Unfortunately 
since I'm a list moderator I can't actually do that...

> I hope the bullet points will be useful to those considering writing Concept 
> documentation.

In case you missed it, there is a fair amount of Concept documentation used by 
several Boost libraries.  Concept documentation, as far as I know, has never 
impacted negatively on the acceptance of a library.  In fact, in my 
experience, it's the other way around.   For example, ASIO, accepted earlier 
this year, uses concept documentation.  But some concept documentation goes 
back to the very beginning of Boost (like operators, vintage 1999).  Here's 
some samples (there are others)

http://asio.sourceforge.net/asio-0.2.0/doc/html/
http://www.boost.org/libs/iterator/doc/iterator_concepts.html
http://www.boost.org/libs/iterator/doc/iterator_archetypes.html
http://www.boost.org/libs/utility/operators.htm

My whole point in this is to make it totally clear for potential library 
authors that Concepts are valid and valuable documentation approach.  If 
people have questions on how best to use concepts, I'm sure there are several 
people on the list that would be happy to help with *best practices* w.r.t 
concept documentation.

Jeff