This is an experimental tool to generate markdown documentation from C++. It consumes .yaml output from clang-doc and formats markdown for serving on fuchsia.dev.
It is not yet hooked up to the build by default. It is invoked using the cpp_docgen() GN template in cpp_docgen.gni. A full example is in the e2e_test directory.
This tool (via clang-doc) reads the comments above functions, classes, structs, defines, enums, etc. and uses these as the documentation for those entities. These comments are called “docstrings.”
The docstrings can be formatted with either // or ///. They must immediately precede the definition with no blank lines to be counted as documentation for that definition.
The contents of the comments is treated as markdown and, to a first approximation, simply copied to the output. The markdown will be converted to HTML by Google devsite, so all devsite markdown features are available, including inline HTML.
// This is the docstring for the function. // // More documentation. Some **bold** and *italic* markdown. You can also have // things like [normal markdown links](https://www.google.com). void MyFunction();
The following sections describe the limited processing that the docgen tool does.
Markdown headings (lines that start with #) are adjusted to appear at the correct level of hierarchy within the document.
// Automatically synchronizes the cardinal grammeter // // # Errors // // This section is formatted by devsite as a definition list. // // ZX_ERROR_NO_RESOURCES // : This error indicates the turbo encabulator was full. // // ZX_ERR_CANCELED // : One of the six hydrocoptic marzel vanes requested a cancelation. zx_status_t SynchronizeCardinalGrammeter();
In this example, the # Errors line will be converted to ### Errors to fall correctly under the automatically generated level 2 heading for the function name. So most headings in docstrings should be level 1 markdown headings.
The exception is if the first line of a docstring starts with a level 1 heading. This heading will be promoted to be the title for the entity rather in place of the generated title (see “Setting the title” below).
Normal markdown links are supported and interpreted by devsite:
[Google](https://www.google.com/)[FIDL wire format](/docs/reference/fidl/language/wire-format)The docgen tool can automatically create links to named entities in the same library by enclosing the name in square brackets and providing no link destination (the part in parenthesis) after the square brackets:
See [SynchronizeCardinalGrammeter()] to synchronize.The doc generateor will look for a symbol (which could be a function, class, define, etc.) called SynchronizeCardinalGrammeter in one of the headers being documented. If found, it will be linked to the correct destination and formatted as code.
[...] can not span lines.If you want to include text in the header that you do not want to appear in the output served by devsite, there are several options.
The first option is to make the comment not be part of the docstring for the item being documented. Normally this means separate the two with a blank line:
// Note: this comment is formatted for docgen so that yadda yadda yadda. This // specific comment will not appear in the generated docs. // Docstring for the thing. double InverseReactiveCurrent();
Since devsite supports HTML tags, you can also include HTML comment tags if you want the comment to appear inline in the docstring. The disadvantage of this approach is that the text will be served on web page to end-user's browser, just not rendered:
// Returns the goniometric data associated with the emcabulator. // // <!-- Note: be sure to keep this section in order! --> // // ...more stuff here... std::vector<int> GetGoniometricData();
Sometimes you don't want a function or structure emitted in the documentation. In these case, you can add the annotation “$nodoc” anywhere in the docstring for the thing you would like to be skipped:
// Private internal function. // $nodoc void EnableQuasistaticRegeneration();
Aside: why not use \nodoc or @nodoc instead of $nodoc, both of which are more often used in similar tools? Clang tries to interpret backslash- and @-annotated words but since it doesn‘t know this command it doesn’t do anything but still strips the word from the output. Therefore, we need a different annotation style.
The docgen tool and clang-doc (the underlying tool) don't support all C/C++ constructs so some generated declarations may be incorrect. In other cases, you may want to format the declaration in some specific way to make it more clear.
In these cases you can add the annotation “$nodecl” anywhere in the docstring for the corresponding entity to skip automatic generation of the declaration.
In such cases, you should provide your own version of the declaration. The autogenerated declarations appear above the rest of the docstring; following this format in your custom declarations will keep the documentation easier to follow.
// $nodecl
// ```
// struct DiffusionIntegrator {
// union {
// int a;
// struct {
// double b;
// char c;
// };
// } u;
// };
// ```
//
// The DiffusionIntegrator collects the interelectrode diffusion in such a
// way that the ...
struct DiffusionIntegrator {
...
};
You can supply content that goes at the top of the generated “index.md” file. It is recommended this just be the README.md file at the toplevel of your library. This should give an introduction to the library and it will be followed by the generated header file and function indices. The title of this file will also define the title of the generated index.md file.
To specify the overview file, use the overview variable in the cppdocgen GN template. This file path is relative to the BUILD.gn directory.
cpp_docgen("my_docs") {
headers = [ ... ]
overview = "README.md"
...
}
You can supply markdown text to be included at the top of the reference for a header file. To count as the documentation for the header (rather than a copyright block or the documentation for something else), the comment must satisfy all of these requirements:
It is recommended that this block go immediately before or after the include guard.
A title will be generated for each reference page based on the header and library name. This may not always be appropriate.
If the header file comment starts with a markdown heading 1 (“#”), that line will be used as the title of the page instead. For example:
// Copyright 2022 blah blah #ifndef MY_LIBRARY_MY_HEADER_H_ #define MY_LIBRARY_MY_HEADER_H_ /// # Deprecated functions in libdoom /// /// The header `<lib/libdoom/deprecated.h>` contains all of the functions /// that are currently deprecated but allowed to be used.
For user-friendliness:
Include the path and name of the header file as the user will type it in their code (likely relative to the library include directory, not the fuchsia repository root). If this is not included in the title, put it near the top of the header documentation text.
Include the name of the library.
Sometimes you will want some functions or defines to appear under the same heading. This can make similar functions much easier to follow.
Two functions are implicitly grouped when they have the same name and no blank or comment lines separating their declarations. Any comment above the first function becomes the comment for all of them.
// Returns an iterator to the beginning of the container. iterator begin(); const_iterator begin() const;
These same rules apply to constructors (which always have matching names). The difference is that constructors will always go under the same “construcors” heading, but there will be different sections within that if there are constructor variants with separate comments.
class MyClass {
// These two will ge grouped together and this will be the docstring for them.
MyClass();
MyClass(int a);
// This one will go in its own section with its own documentation.
MyClass(std::string a);
Functions (even with non-matching names) and #defines can also be grouped explicitly. To do this, list the items with no blank or comment lines separating them, provide a comment above the first item, and start that comment with a markdown heading 1 (“# ...”). The heading will become the title for all items in the group:
/// # ZX_RIGHT_... defines /// /// These constants define the rights for objects. #define ZX_RIGHT_NONE 0 #define ZX_RIGHT_DISINTEGRATE 1 #define ZX_RIGHT_STAPLE 2 /// # begin()/cbegin() /// /// These functions return a (possibly const) iterator to the beginning of the /// container. iterator begin(); const_iterator cbegin();
It is good practice to include as much of the name as practical in the title. This is what the user will be scanning for and it should match with the other titles which use the raw function/define names. It's best to end the title with “macros” or “defines” to match the generated titles of other sections.
In cases where there is a group of related defines that need individual documentation, the recommended formatting is to create a group (so they will all be under one heading with one section showing all the declarations in-order) and then include per-flag documentation in headings under that. The cppdocgen tool will indent the headings automatically to be within the group.
// Encabulator flag macros // // These macros define bits that can be used in the `flags` parameter of the // [enable_encabulator()] function. // // # ENCABULATOR_ENABLE_TURBO // // Enables the turbo mode of the encabulator. Etc... // // // # ENCABULATOR_ENABLE_MARZELVANES // // Documentation for this flag... #define ENCABULATOR_ENABLE_TURBO 1 #define ENCABULATOR_ENABLE_MARZELVANES 2