Whether browsing doxygen docs or source code, for any given symbol, line, block, or file, it is not sufficiently clear what the relevant API layer is for a symbol or behavior. API separation is attempted with the aid of custom scripts (typically run only after development has taken place) and brittle use of doxygen XML.
Proposal 0: Library API is not a superset of the public API.¶
"Developer documentation" may be a superset of API usage documentation if the term means that additional design and implementation notes are exposed.
But this is not the same as the distinction between documentation for different API scopes.
Currently, it is not sufficiently obvious (when browsing "library" level documentation) which documented entities are in the public API scope or not. Conversely, the public API documentation often references opaque types that have no visible documentation at all, even though the types are documented, because of difficulties resolving doxygen visibility.
We can normalize our usage of
\internal to exclusively indicate details (design or implementation notes) that are beyond the scope of an API reference, and decouple this doxygen construct from annotations of API layers.
We can build discrete public and library-internal API docs from separate sources, rather than as a three-tiered visibility mask. This also would allow
\internal to be used to toggle extra design/development detail independently of the API scope.
Proposal 1: Link API level, documentation target, and header location / include scope.¶
Define API layers in terms of header file location and CMake targets.
- A header file defines interfaces in exactly one API layer. Since we are starting from scratch on declaring what is in the public API, this does not present an immediate obstacle to adoption, but establishes that previously public headers may need to be ported rather than simply re-declared as public. This is probably a good thing. See also #3288.
- It should no longer be necessary to use extra doxygen mark-up to declare API scope within files.
Proposal 2: Comprehensive public API documentation.¶
All publicly visible symbols are documented to the extent of their visibility in the public API documentation.
- Forward declarations or other opaque symbols may appear in multiple headers with different documentation at different levels. Primary documentation should be in a single location. Other locations should tersely refer to the file and API layer in which the symbol is documented.
Proposal 3: Make documentation visibly distinct for different API layers.¶
Different graphical style, for instance. Consider Sphinx for public API and doxygen for library API developer docs.