API Documentation Tools

Generating API Documentation

LIBRA provides targets for generating the documentation with:

doxgyen

Checking API Documentation

LIBRA provides tools for checking API documentation with:

doxygen (make apidoc-check-doxygen)
clang (make apidoc-check-clang)

None of these targets depend on the main project, and so can be run in CI prior to the build stage, if desired.

Several tags are modified in the generated Doxyfile:

WARN_AS_ERROR=FAIL_ON_WARNINGS
QUIET=YES

This checker can warn on missing/malformed documentation, but cannot check documentation for consistency with the code itself.

This checker only checkers existing documentation for consistency; if you forget to document something, no error will be emitted. It will also check for consistency between documentation and code (e.g., the documented parameter has the same name as the parameter in the code), since it is AST aware.

If your project depends on/links with 3rd party libraries which are not “system” libraries, then clang will warn about documentation issues in the 3rd party headers as well, and error out, even if your documentation is clean. This can happen with LIBRA_DRIVER=CONAN, or (more rarely) stand-alone 3rd party libraries don’t specify their includes properly.

There are two solutions to this:

Modify one or more of the {INCLUDE_DIRECTORIES, INTERFACE_INCLUDE_DIRECTORIES} properties to mark the include directories from the 3rd party libraries as SYSTEM so that they get specified on the compiler command line as isystem.

Wrap the problematic 3rd party headers in:

#pragma clang diagnostic push
#pragma clang diagnostic ignored "-Wdocumentation"
#include <3rdparty/problem.hpp>
#pragma clang diagnostic pop

The first way is less invasive, and so should be preferred.