Doxygen style guide#

Pigweed’s C/C++ API reference is powered by Doxygen. All Doxygen comments in Upstream Pigweed must adhere to this style guide.

If you’re looking for help with contributing to the upstream Pigweed Doxygen system, see Doxygen contributor’s guide.

Adopting this style guide#

Other projects are welcome to adopt this style guide. A few other Google projects already have.

To propose changes to this style guide, file a bug, submit a change, or start a discussion.

Note

The rules in Upstream Pigweed rules only apply to upstream Pigweed and aren’t suitable for general adoption because they rely on Doxygen customizations that only exist in the upstream Pigweed repository.

Comments#

Always use the /// style. No other comment style is allowed.

Yes

Triple slash style, single line:

/// …

Triple slash style, multiple lines:

/// …
/// …
/// …

Commands#

Always use the @ style for special commands. The \ style is not allowed.

Yes

/// @param[in] n The number of bytes to copy.

No

/// \param[in] n The number of bytes to copy.

@returns#

Always use @returns, never @return.

@param#

Style rules related to the @param special command.

Direction#

Always provide the parameter’s direction annotation.

Yes

/// @param[in] n The number of bytes to copy.

No

/// @param n The number of bytes to copy.
Bidirectional values#

Always use in,out.

Yes

/// @param[in,out] buffer The buffer to store data in.

No

Incorrect order:

/// @param[out,in] buffer The buffer to store data in.

Using space instead of comma:

/// @param[in out] buffer The buffer to store data in.

No whitespace between the values:

/// @param[inout] buffer The buffer to store data in.

Upstream Pigweed rules#

Additional style guide rules for Doxygen comments in upstream Pigweed.

The following style rules are not appropriate for general adoption because they depend on Doxygen customizations that only exist within the upstream Pigweed repository.

pw::Status aliases#

Use the following aliases when referring to pw_status codes:

  • @OK

  • @CANCELLED

  • @UNKNOWN

  • @INVALID_ARGUMENT

  • @DEADLINE_EXCEEDED

  • @NOT_FOUND

  • @ALREADY_EXISTS

  • @PERMISSION_DENIED

  • @RESOURCE_EXHAUSTED

  • @FAILED_PRECONDITION

  • @ABORTED

  • @OUT_OF_RANGE

  • @UNIMPLEMENTED

  • @INTERNAL

  • @UNAVAILABLE

  • @DATA_LOSS

  • @UNAUTHENTICATED

Functions that return pw::Status#

Use the following pattern:

/// @returns
/// * <alias>: <description>
/// * <alias>: <description>

Where <alias> is one of the pw::Status aliases and <description> is an explanation of what the status code means for this particular function or method.

Important

There must be not be any blank lines between the bullet list items. Doxygen ends the @returns block when it encounteres a blank line.

Example:

/// @returns
/// * @OK: The bulk read was successful.
/// * @RESOURCE_EXHAUSTED: The remaining space is too small to hold a new
///   block.

Functions that return pw::Result#

Use the following pattern:

/// @returns @Result{<value>}
/// * <alias>: <description>
/// * <alias>: <description>

Where <value> describes the value that’s returned in the OK case, <alias> is one of the pw_status error codes and <description> is an explanation of what the error code means for this particular function or method.

Example:

/// @returns @Result{a sample}
/// * @RESOURCE_EXHAUSTED: ADC peripheral in use.
/// * @DEADLINE_EXCEEDED: Timed out waiting for a sample.
/// * Other statuses left up to the implementer.

See TryReadFor() to view how this example gets rendered.

On this page