Adding Documentation to C++ Code

Documentation for C++ is provided through Javadoc-style comments and generated using Sphinx, Doxygen, and Breathe.

Documentation is kept in header files with the .h extension as well as in .cpp, cu, and cuh files. In these files, everything between #ifndef DOXYGEN_THIS_WILL_BE_SKIPPED and #endif will be hidden from the HTML output. When you add descriptionss to a function, make sure that the #ifndef and #endif are configured correctly.

Follow these instructions to document, generate, and publish a new C++ docstring:

1. API methods are grouped together by group tags for better organization in Sphinx. If a desired method group for the target method is not defined yet, define it near the top of the relevant header file with the @defgroup command:

   /// @defgroup example-method-group Example Method Group
   /// This is a description of the example method group.
   

2. Add the docstring directly above the target method’s declaration. At a very minimum, please add descriptions of:

   • The method’s functional behavior

   • The type parameters, as denoted by the @tparam tag

   • The arguments, as denoted by the @param tag

   • The return value, as denoted by the @return tag

   • The exceptions that can be thrown (if applicable), as denoted by the @throw tag

   Other commands such as @note, @warning, and @see should be added as needed.

   Here is an example C++ docstring:

   /// @ingroup example-method-group
   ///
   /// @brief A very short description of `example_method`.
   ///
   /// Here is a much longer description of `example_method` with code examples:
   ///
   /// **Example:**
   /// ```python
   /// # Here is a Python code block
   /// def foo(lst: list[int]) -> list[int]:
   ///   return [ x ** 2 for x in lst ]
   /// ```
   ///
   /// And here is a verbatim-text diagram example:
   ///
   /// @code{.unparsed}
   ///   .------+---------------------------------.-----------------------------
   ///   |            Block A (first)             |       Block B (second)
   ///
   ///   +------+------+--------------------------+------+------+---------------
   ///   | Next | Prev |   usable space           | Next | Prev | usable space..
   ///   +------+------+--------------------------+------+--+---+---------------
   ///   ^  |                                     ^         |
   ///   |  '-------------------------------------'         |
   ///   |                                                  |
   ///   '----------- Block B's prev points to Block A -----'
   /// @endcode
   ///
   /// @tparam T Description of `T`
   /// @tparam Alignment Description of the `Alignment` value
   /// @param param1 Description of `param1`
   /// @param param2 Description of `param2`
   ///
   /// @return Description of the method's return value.
   ///
   /// @throw std::bad_alloc if allocation failed
   /// @throw std::logic_error if a logic error occurs
   ///
   /// @note This is an example note.
   ///
   /// @warning This is an example warning.
   ///
   /// @see For more info on Doxygen docstrings, see
   /// <a href="https://www.doxygen.nl/manual/commands.html#cmdlink">here</a>.
   template <typename T, std::size_t Alignment>
   int32_t example_method(T param1, float param2);
   

3. On the Sphinx documentation side, add a doxygengroup directive to the corresponding .rst file. If an .rst file for the corresponding header file does not exist, create a new one by the same name as the header file. Using the above example:

   .. doxygengroup:: example-method-group
     :content-only:
   

4. Make sure the .rst file is included in to the toctree in index.rst (e.g. FBGEMM_GPU C++ API).

5. The C++ source header file needs to be in one of the directories listed in the INPUT parameter in Doxygen.ini. In general, this has already been taken care of, but if it’s in a directory not listed, be sure to append the directory path to the parameter.

6. Verify the changes by building the docs locally with Building the Documentation or submitting a PR for a Netlify preview.

---

The Doxygen example above generates the following HTML output:

template<typename T, std::size_t Alignment>
int32_t example_method(T param1, float param2)

A very short description of example_method.

Here is a much longer description of example_method with code examples:

Example:

# Here is a Python code block
def foo(lst: list[int]) -> list[int]:
  return [ x ** 2 for x in lst ]

And here is a verbatim-text diagram example:

.------+---------------------------------.-----------------------------
|            Block A (first)             |       Block B (second)

+------+------+--------------------------+------+------+---------------
| Next | Prev |   usable space           | Next | Prev | usable space..
+------+------+--------------------------+------+--+---+---------------
^  |                                     ^         |
|  '-------------------------------------'         |
|                                                  |
'----------- Block B's prev points to Block A -----'

See also

For more info on Doxygen docstrings, see here.

Note

This is an example note.

Warning

This is an example warning.

Template Parameters:

• T – Description of T

• Alignment – Description of the Alignment value

Parameters:

• param1 – Description of param1

• param2 – Description of param2

Throws:

• std::bad_alloc – if allocation failed

• std::logic_error – if a logic error occurs

Returns:

Description of the method’s return value.