Re: [boost] [Advice] Documenting the "refined by" relation for concepts

Subject: Re: [boost] [Advice] Documenting the "refined by" relation for concepts
From: Louis Dionne (ldionne.2_at_[hidden])
Date: 2015-06-15 16:45:07

Gavin Lambert <gavinl <at> compacsort.com> writes:

> 
> [...]
> 
> Well, I'm not a seasoned generic library writer, but in my view as a 
> user of such libraries it is always very useful to be able to navigate 
> from a base class/interface to its derived classes in the documentation, 
> and the same would apply to concepts.  (Not just derived/refined 
> concepts, but also if there are classes provided in the library that 
> actually implement these concepts.)
> 
> One of the reasons that this is sometimes left out of documentation is 
> that it's usually an open relationship and thus can never be complete -- 
> other libraries or the user's own code could (and often does) add 
> additional types that "should" have been listed, though of course they 
> can't be.  However I don't think that's a good reason to not document 
> this relation for the types that are actually provided by the library, 
> though.

I agree that providing a list of the sub-concepts defined by the library 
is useful to the user. I think I'll do that in one way or the other, perhaps
like Vinicius suggested (in a "See also" section) or by providing a 
"Non-exhaustive list of sub-concepts" thing. In all cases, I must find a way 
to handle this automatically, or I'll regret this really fast.

Regards,
Louis