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

Subject: Re: [boost] [Advice] Documenting the "refined by" relation for concepts
From: Gavin Lambert (gavinl_at_[hidden])
Date: 2015-06-14 23:31:02

On 14/06/2015 08:12, Louis Dionne wrote:
> When documenting a concept in a generic library, it is common to include what
> this concept is a "refinement of", i.e. which other concept(s) it specializes.
> For example, see the ForwardContainer concept from the SGI STL [1], which
> is a refinement of the Container concept.
>
> I find documenting this relation very useful. However, I have never seen the
> reverse relation of being "refined by" documented. It has been suggested to
> me [2] that Hana should document this "refined by" relation. Having never
> seen it done before, I'd like to know what the seasoned generic library
> writers think about it.

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.

(The other reason that it's often left out is that many libraries only 
define purely-open concepts with no internal implementations and no 
refinements, so there's no relations *to* document.)

That's my $0.10, anyway.  (Due to exchange rates and not having any 
smaller coins any more.)