Leverage Re-usable Documentation Techniques for High-Level Documentation [DS23] [WHERE]
Tip DS23
When creating high-level overview documentation, you may sometimes have to place documentation further from the code than you’d like. In these cases, look for techniques to either (1) minimize the distance between the comments and the code or (2) connect the further-away comments to the code itself. Leverage capabilities of your documentation generator where possible.
Most documentation generators support tags where you can directly “point” or “reference” other parts of the code documented with the generator. The following are some examples:
If you just need to point other programmers to parts of code, the above tags might be useful. See the following Doxygen example:
/// Holds computer graphics code.
///
/// This library spans a diverse range of computer graphics concepts such as:
/// - [Using different hardware for rendering](\ref GRAPHICS::HARDWARE)
/// - Different [rendering](\ref GRAPHICS::RENDERING_ALGORITHMS),
/// [shading](\ref GRAPHICS::SHADING), and
/// [lighting](\ref GRAPHICS::LIGHTING) algorithms
/// - [Data structures for 3D mathematics](\ref GRAPHICS::GEOMETRY)
/// - [Different 3D model formats](\ref GRAPHICS::MODELING)
/// - [Different image formats](\ref GRAPHICS::IMAGES)
/// - [Graphical user interfaces](\ref GRAPHICS::GUI)
///
/// Classes applicable across a wide variety of these areas are in the root namespace.
/// However, each of the above concepts requires a lot of code to handle,
/// so code related to specific concepts for which many classes exist have
/// been placed in their own sub-namespaces.
/// Consult documentation for each sub-namespace for more details.
///
/// Performance of all code in this namespace is a key quality attribute,
/// so all code should be heavily optimized.
namespace GRAPHICS
However, if you actually need to generate final HTML documentation with documentation content on the same page from multiple places, the above kind of “reference links” won’t work. Doxygen has several tags - \copydoc, \copybrief, and \copydetails - that might be usable, depending on your use case. Here’s an example:
/// Holds computer graphics code.
///
/// This library spans a diverse range of computer graphics concepts such as:
/// - Using different hardware for rendering
/// - Different rendering, shading, and lighting algorithms
/// - Data structures for 3D mathematics
/// - Different 3D model formats
/// - Different image formats
/// - Graphical user interfaces (GUIs)
///
/// Classes applicable across a wide variety of these areas are in the root namespace.
/// However, each of the above concepts requires a lot of code to handle,
/// so code related to specific concepts for which many classes exist have
/// been placed in their own sub-namespaces. The following provides details
/// on key namespaces:
/// - \copydoc GRAPHICS::HARDWARE
/// - \copydoc GRAPHICS::RENDERING_ALGORITHMS
/// - \copydoc GRAPHICS::SHADING
/// - \copydoc GRAPHICS::LIGHTING
/// - \copydoc GRAPHICS::GEOMETRY
/// - \copydoc GRAPHICS::MODELING
/// - \copydoc GRAPHICS::IMAGES
/// - \copydoc GRAPHICS::GUI
///
/// Performance of all code in this namespace is a key quality attribute,
/// so all code should be heavily optimized.
namespace GRAPHICS