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.
/*! ... */ documents an entity for whoever uses it: what it is, how to use
it, what it costs. It stands right above the declaration, in the header.// comment./* ... */, each line
starting with ` * , without the !` that would make it Doxygen’s.A comment says what the code cannot say for itself. It does not repeat the code.
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:
enabled_ in Display..cpp, when it explains that.\note.Only a NOLINTNEXTLINE stands between a block and its declaration, as it has to stand right above
the line it is for.
/*!
* \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);
/*! on a line of its own, each further line starting with ` * , and / on a line of its
own. A block that holds only a brief is one line: /! \brief The number of rows. */`./*!< ... */, when the
brief is all it needs and fits on the line. If it does not, a one-line block
/*! \brief ... */ stands above it.\brief, never with @.\param[in] column; nothing is aligned
in columns.\return above does. make fmt indents it so, after clang-format; make lint fails where a
line is not indented so. Both run the template’s tools/lib/doc_indent.py.| 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.
column and
row.”, “Shows the time in words.”, “Returns the brightness the display is set to.”\code{.cpp} ... \endcode where a call is clearer than a sentence. Keep it short
and make it compile.column, entities as DisplayWords. Doxygen links an entity
by its name; write Display::SetPixel() to link a member.tools/documented-sizes.py, as any
other size in this repository does; see CLAUDE.md..cpp has no Doxygen block.
Where there is something to say, a // or /* */ comment says it at the definition. Two
reasons, and both matter: a helper earns its own name precisely because that name carries the
meaning a comment would otherwise have to (see CLAUDE.md), so a \brief would only say it
again; and EXTRACT_PRIVATE is NO in the Doxyfile, so Doxygen never reads a block there -
make docs would not check it, and a \param naming a parameter that has since been
renamed would never be caught. An unchecked block is worse than a plain comment, because it
looks checked.Clock::MinuteType and AnimationCube::BorderStateType are. A name carries what a function
does; it does not carry what a field means or why a layout is that way.\copydoc, rather than a second text that would drift from it. Overloads that differ only
in their parameters share one text the same way.Pixels or System, is documented in each
backend, as each says how it does it on its hardware.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.”
make docs, the template’s tools/docs.sh, has Doxygen read the blocks, once per backend as
docs_inputs() of tools/project.sh lists them, and fails on every warning but a missing
\return: a block Doxygen cannot read, a parameter without its \param, an entity without a
block. A warning of src/, which every run reads, counts once. It writes what Doxygen made of
the blocks into build/docs/<n>/html, one for each backend.clang’s -Wdocumentation, through clang-tidy in static-analysis.yml and through clangd,
checks each block against the declaration it stands at: a \param whose name the function does
not have, a \return on a function that returns nothing, an empty command, an unknown command.
clangd shows these in the editor as you type. A backslash meant as a char is written \\, or
clang takes it for a command.
tools/lib/doc_indent.py, through make lint, checks that the lines continuing a command
are indented under its text.All three run in static-analysis.yml on every pull request.
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.