Improve "documentation inheritance"

[joshuahansel]

Motivation

Users go to an object documentation page and see only what is explicitly included on the page, but a class may inherit from other objects and base classes, which may have their own documentation pages. Often any parent class documentation pages are not linked from the child class pages and may be unknown to the reader.

Design

I propose two objectives to help with this:

• An automatically-generated inheritance tree or table. It could be something like doxygen's inheritance tree diagram, where the vertical axis is the inheritance level:

  B1 B2
  |  |
   A
  

  or it could be rotated 90 degrees to make something like a table of contents:

  A
    B1
      C1
      C2
    B2
  

  This table could be generated by some new command !inheritance tree or something. It could be collapsed by default on doc pages.
• In parameter table, include a line for each parameter giving a link to the doc page of the class that added it (if no doc page is available, just text).

As for the how of these items, that's the hard part - I don't know how feasible these objectives are. For the first one, we know that doxygen does something to generate its diagrams, so we could potentially apply the same machinery. I don't know if C++ executables can be queried for inheritance information. If determining the actual C++ inheritance isn't very feasible, then perhaps we could at least get parameter inheritance via calls like += Base::validParams() or something along these lines.

Impact

Improved documentation.

[GiudGiud]

Love it. Determining the inheritance tree can be done by parsing headers, as is done for determining the children classes. It's not super robust for templated classes though