Documentation strings

We use doxygen + sphinx + breathe to render libdnf5 documentation.

A typical docstring contains the following:

  • Description (mandatory; we don’t use @brief as it doesn’t seem to impact the rendered output)

  • a blank line

  • @param - argument name and description (only if applicable, can be specified multiple times)

  • @return - description of the returned value (only if applicable)

  • @exception - exception type and description (only if applicable, can be specified multiple times)

  • @since - version an entity become available (mandatory)

  • @deprecated - reason why an entity is deprecated (only if applicable)

  • @note - note text (optional)

  • @warning - warning text (optional)

We highlight identifiers with `backticks`.

Example:

/// Split a string by a delimiter into a vector of strings
///
/// @param text             Input text.
/// @param delimiter        A delimiter we're using to split the text.
/// @param max_items        Limit number of splits to produce a vector containing up to `max_items` items.
/// @return Split text.
///         A continuation line for the return value description.
/// @exception std::out_of_range    Value of the `max_items` argument is out of expected range.
/// @since 5.0
std::vector<std::string> split(std::string text, std::string delimiter, int max_items);

We also reference DNF 4 and libdnf5 0.x API classes, methods, attributes or functions that the subject of the documentation replaces by using @replaces command followed with a description of the replaced entity:

  • <project>:<path>:class:<ClassName>

  • <project>:<path>:method:<ClassName>.<method_name>(args)

  • <project>:<path>:attribute:<ClassName>.<attribute_name>

  • <project>:<path>:function:<function_name>

We keep these in regular comments rather than docstrings to avoid spamming the rendered docs.

Example:

/// <docstring>
//
// @replaces dnf:dnf/package.py:attribute:Package.name
// @replaces libdnf5:libdnf5/hy-package.h:function:dnf_package_get_name(DnfPackage *pkg);
std::string get_name() const;