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