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-15 02:26:09

On 15/06/2015 17:05, Robert Ramey wrote:
> On 6/14/15 8:31 PM, Gavin Lambert wrote:
>> 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.)
>
> Any derived concepts that the library includes will have their own pages
> which will refer to the base concept so it's not like anything will be
> lost but not including a pointer from the base to the derived.

Yes, something is lost: if you are looking at the documentation for the 
base type/concept, you have no way to find any derived type/concepts 
without trawling the entire documentation and hoping that they have 
sufficiently similar names to be recognisable.  (Which is usually the 
case, but not always.)

> In fact, this might well be confusing as it might obscure the essential
> dependency relationship.

I don't see how -- you can clearly indicate the difference between base 
and derived by putting them in different sections or with appropriate 
headings.

Possibly this particular style is only suited to a "large" library, but 
the .NET Framework documentation has a good example of a minimalist 
style that still conveys the necessary information: an "Inheritance 
Hierarchy" section that shows a tree with base types above and derived 
types below the current type.

Libraries with only a small tree of types/concepts may be better served 
with a more verbose style though, for improved clarity.

> This is especially true as the library undergoes maintenance.

Ideally the tools should keep the docs up to date automatically (at 
least the reference section).

> I would recommend doing it the standard way as illustrated by
> the SGI documentation.

The SGI docs sometimes list the derived types/concepts in the base doc's 
"See Also" section, which is good.  It would be better if it were called 
out more explicitly, though, as otherwise they're mixed in with other 
types that have a lesser relationship; and it would be better still if 
it were more consistent about listing them at all.

> And most library actually only have a few new concepts anyway. I haven't
> seen any other than STL which define more than a small # of concepts (5?).

I did make that point.  (Boost.Asio has quite a few, incidentally.)