summaryrefslogtreecommitdiffstats
path: root/eng/coding-doxygen.rst
blob: b2e6b613925d5ba037ec0a39f1dc24b3916388d5 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
.. SPDX-License-Identifier: CC-BY-SA-4.0

.. Copyright (C) 2019 embedded brains GmbH

.. _DoxygenGuidelines:

Doxygen Guidelines
==================

Group Names
-----------

Doxygen group names shall use
`CamelCase <https://en.wikipedia.org/wiki/Camel_case>`_.
In the RTEMS source code, CamelCase is rarely used, so this makes it easier to
search and replace Doxygen groups.  It avoids ambiguous references to
functions, types, defines, macros, and groups.  All groups shall have an
``RTEMS`` prefix.  This makes it possible to include the RTEMS files with
Doxygen comments in a larger project without name conflicts.  The group name
shall use `Title Case <https://en.wikipedia.org/wiki/Letter_case#Title_Case>`_.

.. code:: c

    /**
     * @defgroup RTEMSScoreThread Thread Handler
     *
     * @ingrop RTEMSScore
     *
     * ...
     */

Use Groups
----------

Every file, function declaration, type definition, typedef, define, macro and
global variable declaration shall belong to at least one Doxygen group.  Use
``@defgroup`` and ``@addtogroup`` with ``@{`` and ``@}`` brackets to add
members to a group.  A group shall be defined at most once.  Each group shall
be documented with an ``@brief`` description and an optional detailed
description.  Use grammatically correct sentences for the ``@brief`` and
detailed descriptions.

For the ``@brief`` description use phrases like this:

* This group contains ... and so on.

* The XYZ Handler provides ... and so on.

* The ABC Component contains ... and so on.

.. code:: c

    /**
     * @defgroup RTEMSScoreThread Thread Handler
     *
     * @ingrop RTEMSScore
     *
     * @brief The Thread Handler provides functionality related to the
     *   management of threads.
     *
     * This includes the creation, deletion, and scheduling of threads.
     *
     * ...
     *
     * @{
     */

     ... declarations, defines ...

     /** @} */

.. code:: c

    /**
     * @addtogroup RTEMSScoreThread
     *
     * @{
     */

     ... declarations, defines ...

     /** @} */

Files
-----

Each header and source file shall have an ``@file`` block at the top of the
file after the SPDX License Identifier.  The ``@file`` block shall precede the
license header separated by one blank line, see :ref:`CCXXHeaderFileTemplate`
and :ref:`CCXXASMSourceFileTemplate`.  The ``@file`` block shall be put into a
group with ``@ingroup GroupName``.  The ``@file`` block shall have an
``@brief`` description and an optional detailed description.  The detailed
description could give an explanation why a certain set of functions or data
structures is grouped in one file.  Use grammatically correct sentences for the
``@brief`` and detailed descriptions.

For the ``@brief`` description of header files use phrases like this:

* This header file provides ... and so on.

* This header file provides the API of the ABC Manager.

* This header file provides interfaces and functions used to implement the XYZ
  Handler.

For the ``@brief`` description of source files use phrases like this:

* This source file contains the implementation of some_function().

* This source file contains the definition of some_data_element.

* This source file contains the implementation of XZY Hander functions related
  to ABC processing.

.. code:: c

    /**
     * @file
     *
     * @ingroup RTEMSScoreThread
     *
     * @brief This source file contains the implementation of
     *   _Thread_Initialize().
     */

Type Definitions
----------------

Each type (``typedef``, ``struct``, ``enum``) defined in a header file shall be
documented with an ``@brief`` description and an optional detailed description.
Use grammatically correct sentences for the ``@brief`` and detailed
descriptions.

For the ``@brief`` description of types use phrases like this:

* This type represents ... and so on.

* This structure represents ... and so on.

* This structure provides ... and so on.

* This enumeration represents ... and so on.

* The XYZ represents ... and so on.

Each type member shall be documented with an ``@brief`` description and an
optional detailed description.  Use grammatically correct sentences for the
``@brief`` and detailed descriptions.

For the ``@brief`` description of types members use phrases like this:

* This member represents ... and so on.

* This member contains ... and so on.

* This member references ... and so on.

* The XYZ lock protects ... and so on.

For the ``@brief`` description of boolean type members use a phrase like this:
"This member is true, if some condition is satisfied, otherwise it is false.".

.. code:: c

    /**
     * @brief The object information structure maintains the objects of an
     *   object class.
     *
     * If objects for the object class are configured, then an instance of this
     * structure is statically allocated and pre-initialized by
     * OBJECTS_INFORMATION_DEFINE() through <rtems/confdefs.h>.  The RTEMS
     * library contains a statically allocated and pre-initialized instance for
     * each object class providing zero objects, see
     * OBJECTS_INFORMATION_DEFINE_ZERO().
     */
    typedef struct {
      /**
       * @brief This member contains the object identifier maximum of this
       *   object class.
       *
       * It is statically initialized.  The object identifier maximum provides
       * also the object API, class, and multiprocessing node information.
       *
       * It is used by _Objects_Get() to validate an object identifier.
       */
      Objects_Id maximum_id;

      ... more members ...
    } Objects_Information;

Function Declarations
---------------------

Each function declaration or function-like macro in a header file shall be
documented with an ``@brief`` description and an optional detailed description.
Use grammatically correct sentences for the ``@brief`` and detailed
descriptions.  Use the descriptive-style for ``@brief`` descriptions, for
example ``"Creates a task."``, ``"Sends the events to the task."``, or
``"Obtains the semaphore."``.  Use "the" to refer to parameters of the
function.  Do not use descriptions like ``"Returns this and that."``.  Describe
the function return in ``@retval`` and ``@return`` paragraphs.

Each parameter shall be documented with an ``@param`` entry.  List the
``@param`` entries in the order of the function parameters.  For *non-const
pointer* parameters

* use ``@param[out]``, if the function writes under some conditions to memory
  locations referenced directly or indirectly by the non-``const`` pointer
  parameter, or

* use ``@param[in, out]``, if the function reads under some conditions from
  memory locations referenced directly or indirectly by the non-``const``
  pointer parameter and the function writes under some conditions to memory
  locations referenced directly or indirectly by the non-``const`` pointer
  parameter.

If the function only reads from memory locations referenced directly or
indirectly by a non-``const`` pointer parameter, then the pointer parameter
should be made ``const``.

For other parameters (e.g. *const pointer* and *scalar* parameters) do not use
the ``[in]``, ``[out]`` or ``[in, out]`` parameter specifiers.

For the ``@param`` descriptions use phrases like this:

* is the ABC.

* indicates what should be done.

* defines the something.

* references the object to deal with.

The phrase shall form a grammatically correct sentence if "This parameter"
precedes the phrase, for example "This parameter is the size of the message in
bytes to send.".

Distinctive return values shall be documented with an ``@retval`` entry.
Document the most common return value first.  Use ``@return`` to describe the
return of non-distinctive values.  Use grammatically correct sentences for the
descriptions.  Use sentences in simple past tense to describe conditions which
resulted in the return of a status value.  Place ``@retval`` descriptions
before the ``@return`` description.  For functions returning a boolean value,
use ``@return`` and a phrase like this: "Returns true, if some condition is
satisfied, otherwise false.".

.. code:: c

    /**
     * @brief Sends a message to the message queue.
     *
     * This directive sends the message buffer to the message queue indicated by
     * ID.  If one or more tasks is blocked waiting to receive a message from this
     * message queue, then one will receive the message.  The task selected to
     * receive the message is based on the task queue discipline algorithm in use
     * by this particular message queue.  If no tasks are waiting, then the message
     * buffer will be placed at the rear of the chain of pending messages for this
     * message queue.
     *
     * @param id The message queue ID.
     * @param buffer The message content buffer.
     * @param size The size of the message.
     *
     * @retval RTEMS_SUCCESSFUL Successful operation.
     * @retval RTEMS_INVALID_ID Invalid message queue ID.
     * @retval RTEMS_INVALID_ADDRESS The message buffer pointer is @c NULL.
     * @retval RTEMS_INVALID_SIZE The message size is larger than the maximum
     *   message size of the message queue.
     * @retval RTEMS_TOO_MANY The new message would exceed the message queue limit
     *   for pending messages.
     */
    rtems_status_code rtems_message_queue_send(
      rtems_id    id,
      const void *buffer,
      size_t      size
    );

.. code:: c

    /**
     * @brief Receives a message from the message queue
     *
     * This directive is invoked when the calling task wishes to receive a message
     * from the message queue indicated by ID. The received message is to be placed
     * in the buffer. If no messages are outstanding and the option set indicates
     * that the task is willing to block, then the task will be blocked until a
     * message arrives or until, optionally, timeout clock ticks have passed.
     *
     * @param id The message queue ID.
     * @param[out] buffer The buffer for the message content.  The buffer must be
     *   large enough to store maximum size messages of this message queue.
     * @param[out] size The size of the message.
     * @param option_set The option set, e.g. RTEMS_NO_WAIT or RTEMS_WAIT.
     * @param timeout The number of ticks to wait if the RTEMS_WAIT is set.  Use
     *   RTEMS_NO_TIMEOUT to wait indefinitely.
     *
     * @retval RTEMS_SUCCESSFUL Successful operation.
     * @retval RTEMS_INVALID_ID Invalid message queue ID.
     * @retval RTEMS_INVALID_ADDRESS The message buffer pointer or the message size
     *   pointer is @c NULL.
     * @retval RTEMS_TIMEOUT A timeout occurred and no message was received.
     */
    rtems_status_code rtems_message_queue_receive(
      rtems_id        id,
      void           *buffer,
      size_t         *size,
      rtems_option    option_set,
      rtems_interval  timeout
    );

.. code:: c

    /**
     * @brief Allocates a memory block of the specified size from the workspace.
     *
     * @param size is the size in bytes of the memory block.
     *
     * @retval NULL No memory block with the requested size was available in the
     *   workspace.
     *
     * @return Returns the pointer to the allocated memory block, if enough
     *   memory to satisfy the allocation request was available.  The pointer is at
     *   least aligned by #CPU_HEAP_ALIGNMENT.
     */
    void *_Workspace_Allocate( size_t size );

.. code:: c

    /**
     * @brief Rebalances the red-black tree after insertion of the node.
     *
     * @param[in, out] the_rbtree references the red-black tree.
     * @param[in, out] the_node references the most recently inserted node.
     */
    void _RBTree_Insert_color(
      RBTree_Control *the_rbtree,
      RBTree_Node    *the_node
    );

.. code:: c

    /**
     * @brief Builds an object ID from its components.
     *
     * @param the_api is the object API.
     * @param the_class is the object class.
     * @param node is the object node.
     * @param index is the object index.
     *
     * @return Returns the object ID built from the specified components.
     */
    #define _Objects_Build_id( the_api, the_class, node, index )

Header File Examples
--------------------

The
`<rtems/score/thread.h> <https://git.rtems.org/rtems/tree/cpukit/include/rtems/score/thread.h>`_
and
`<rtems/score/threadimpl.h> <https://git.rtems.org/rtems/tree/cpukit/include/rtems/score/threadimpl.h>`_
header files are a good example of how header files should be documented.