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