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.)