Learn how Docuriser turns C++ headers and their doc comments into class, struct, and header pages, and how to check what is still undocumented.
For C++ projects, Docuriser reads your public headers with libclang and turns their declarations and doc comments into an API reference: a page per class and struct, a page per header, and a sidebar that groups them. This guide covers what gets picked up, how to write comments that render well, and how to check what's still undocumented before a release.
The API reference comes from the build.includes[] directories in your repository's .docuriser manifest (see the configuration reference). Every header under them is parsed; build.external[] adds include paths the parser needs without documenting them, and build.defines[] defines macros for the parse:
{
"format": 1,
"build": {
"includes": [ "include/Layers/" ],
"external": [ "include/" ],
"defines": [ "LAYERS_EXPORT=" ]
}
}
Defining export macros away (LAYERS_EXPORT=) keeps them out of the parsed declarations. Projects without build.includes simply have no API reference; their docs are topics only.
A declaration is documented when it is public and declared in one of the parsed headers:
using, typedef, and alias templates), and enums with their values.Some declarations are always left out: anything private or protected (including nested types), anonymous namespaces, friend declarations, forward declarations, member functions defined outside their class (the in-class declaration is what's documented), and macros. Declarations only reached through another header's #include belong to that header, not the one including it.
Put the comment directly above the declaration it documents. Block comments (/* */, /** */, /*! */) and runs of line comments (///, //!, //) all work, and the comment markers and shared indentation are stripped:
/*
Converts a declaration into a list of targets where declaration names are
expanded at all levels. (See LTarget)
```
(Title,Description) // 2 targets
```
*/
std::vector<LTarget> expand_declaration(const LDeclaration& declaration);
struct LTarget
{
/// The parent names in the target's hierarchy.
LStringList path;
};
Comments are Markdown: fenced code blocks get syntax highlighting, and code spans, lists, links, quotes, and headings all render. A // line inside a block comment's code example is kept as written, so commented example code is safe.
The comment's first paragraph is its brief: header pages show it beside each type and alias in their summary tables, so lead with one sentence that says what the declaration is.
For enum values, put each value's comment on its own line above it. A comment that shares a line with the previous value (Word, /* note */ End) isn't attached to anything.
Class and struct pages open with the type's name and kind ("LTarget Struct", "LConnector Class Template"), its #include line (linked to the header's page), and its inheritance. Then come the sections the type has, each left out when empty:
outer-inner.html).Header pages (lloader.h.html) summarize everything the header declares: its types with their briefs, then its aliases, enums, and functions, followed by full documentation for the aliases, enums, and functions (types document on their own pages). This is where free functions live. Two headers that share a file name are told apart by their full include path.
Across all pages, documented types, aliases, and enums are linked wherever they appear in a signature, so const LDeclaration& links to LDeclaration, and LString links to its entry on lstring.h's page. Standard library names are never linked. Overloads each get their own anchor: the first keeps the plain name (#resize) and later ones are numbered (#resize-2), so links to a specific overload land on it.
Each built version's sidebar lists its API reference in three sections, Classes, Structs, and Headers, after the Topics. A section with nothing in it is hidden, and nested types are reached from their owner's page rather than listed. On a doc page, the section holding the current page opens with that page highlighted.
The lists come from the api.json index each version build writes beside its pages. A version built by an older Docuriser has a classes.json instead and keeps working: its sidebar lists all of its pages under Classes until the version is rebuilt.
Every build ends its log with a coverage summary: one line per kind of declaration, counting the public declarations that have a doc comment.
[Engine] Doc comment coverage:
[Engine] classes: 10 of 10 documented
[Engine] structs: 13 of 13 documented
[Engine] member functions: 94 of 102 documented (8 undocumented)
[Engine] member variables: 5 of 39 documented (34 undocumented)
[Engine] functions: 12 of 14 documented (2 undocumented)
The undocumented names themselves are logged at the advanced level, listed under their kind with parameter types so overloads are distinguishable. In the desktop app, check Advanced in the build panel to see them; the CLI prints them in full. Destructors aren't counted, since they rarely need their own docs.
Every page the API reference generates is marked as generated, and a version build deletes the previously generated pages before writing new ones. A class or header you removed from the source doesn't leave an orphan page behind. Topic pages, the license page, and anything else in the version directory are never touched.