tree: 504d99f4d0aac67e44aeb555270dbc3352b18d96 [path history] [tgz]
  1. clangdoc/
  2. cmd/
  3. docgen/
  4. e2e_test/
  5. BUILD.gn
  6. clang_doc.gni
  7. clang_doc_generate_source.py
  8. clang_doc_invoke.py
  9. cpp_docgen.gni
  10. OWNERS
  11. README.md
tools/cppdocgen/README.md

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 ready for general use. It has many limitations and bugs and is not yet hooked up to the build.

Instructions for running manually. It is currently very involved and will be streamlined over time.

  • Create a .cc file in the target you want to document and include all of the headers you want to generate documentation for. It can be otherwise empty.

  • To do a build.

  • Run clang-doc on that output, substituting the name of the .cc file from the first step:

clang-doc --format=yaml -p=out/x64 --executor=all-TUs --filter=<NAME-OF-CC-DOC-FILE>
          --output=<SOME-TEMP-DIR> out/<BUILD-DIR>/compile_commands.json
  • Run cppdocgen on that output, re-listing the headers you want to include documentation for (relative to the build dir) and providing input (the temp directory generated by clang-doc) and output (for the markdown files) directories:
out/<BUILD-DIR>/host_x64/cppdocgen --indir=<TEMP-DIR-FROM-ABOVE>
    --outdir=<OUT-DIR> --strip-include-elts=6
    --source-url="https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/"
    ../../sdk/lib/fdio/include/lib/fdio/directory.h
    ../../sdk/lib/fdio/include/lib/fdio/fd.h

Controlling the output

Per-header documentation

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 must be deliniated with “///” comments at the beginning of the line.
  • It must be followed with a blank line.
  • It must appear before any non-preprocessor lines (only “#” and “//” lines are allowed before it).

It is recommended that this block go immediately before or after the include guard.

Setting the title

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.

Grouping functions and defines into one heading

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