Wordclock — a German word clock (Wortuhr)

Documenting the code

How the code of Wordclock is documented: which comments are Doxygen blocks, what each block says, and how the style is checked. The style is the one of Utl and MaxMatrix, so that every project documents alike. It holds for src/ and platform/; the tests keep a plain comment at the top and one above each test.

The blocks are read in the code and checked in CI; no reference is published from them. Wordclock is a firmware, and the reader of a block is the next person who calls or changes the code.

Two kinds of comment

A comment says what the code cannot say for itself. It does not repeat the code.

Where a comment on the implementation stands

Where the code it explains is, never between a Doxygen block and its declaration, where it would read as a second comment of no one:

Only a NOLINTNEXTLINE stands between a block and its declaration, as it has to stand right above the line it is for.

The block

  /*!
   * \brief Lights the pixel at `column` and `row` in the colour of the display.
   *
   * \param[in] column The column of the grid, counted from 0.
   * \param[in] row The row of the grid, counted from 0.
   * \return kEOk, or kENotOk if `column` or `row` lies off the grid; the pixels are then left as
   *         they were.
   */
  StdReturnType SetPixel(byte column, byte row);

The parts, in this order

Part Says
\brief One sentence, ending in a full stop. Always written out.
Description After an empty line: what the caller has to know beyond the brief, in a few short paragraphs.
\tparam Each template parameter that the caller chooses.
\param[in], [out], [in,out] Each parameter, with its direction.
\return What comes back. For a StdReturnType, when kENotOk comes back and what is left as it was. A one-line block whose brief already says it, “Returns the number of rows.”, leaves it out.
\pre What the caller must ensure, such as Init() first.
\note, \warning What is easy to miss. \warning only where a mistake is costly.
\see A related entity, where the link helps.

A function that returns nothing has no \return. Every parameter has its \param, even the only one. A part that has nothing to say is left out. \details is not written: the description is the paragraphs after the brief.

The brief

The description

What is documented

A file

Every file of src/, platform/ and test/ starts with the licence, as // lines that tools such as REUSE read and cpplint checks for, the tests and their stubs included. A file outside the tests then has a block for the file:

// Copyright 2017 Andreas Burnickl
// SPDX-License-Identifier: GPL-3.0-or-later

/*!
 * \file
 * \brief The display: the pixels of the letter grid, with brightness, colour and current limit.
 */

The year is the one of the file’s first commit. The brief of a header says what it declares; the brief of a source with a header of its own says what the source adds, “The steps of the fade animation.”

Checking

All three run in static-analysis.yml on every pull request.

Writing a block

The dev container has the extension “Doxygen Documentation Generator”. Type /*! above a declaration and press Enter: it writes the skeleton of this style, with a \param for each parameter and a \return for a function that returns a value. The text is yours to write.