summaryrefslogtreecommitdiffstats
path: root/eng/coding-doxygen.rst
blob: 9068074eeb741bfc450cf05c11f03be5addebdd3 (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
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
.. comment SPDX-License-Identifier: CC-BY-SA-4.0

.. COMMENT: COPYRIGHT (c) 2018.
.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project

General Doxygen Recommentations
===============================

.. COMMENT: TBD - Convert the following to Rest and insert into this file
.. COMMENT: TBD - https://devel.rtems.org/wiki/Developer/Coding/Doxygen

.. sidebar:: *History*

  RTEMS is much older than Doxygen (http://www.doxygen.org/) and
  the documentation in the .h files was obviously not written with
  Doxygen markup in mind. In 2007, Joel Sherrill undertook to convert the
  documentation in the .h and .inl files in the RTEMS SuperCore? to Doxygen
  format. As a result of this effort, the Doxygen for the development
  version of the RTEMS is now built automatically periodically and made
  available on the RTEMS Website. In April 2008, Joel Sherrill began to
  update the Classic API (e.g. cpukit/rtems) .h files to include Doxygen
  markup. Now, RTEMS has nice Doxygen markup including state and sequence
  diagrams.

Doxygen Best Practices
----------------------

* Do not use ``@a``. Instead use ``@param`` to document function parameters.
* Do not use ``@return``. Instead use ``@retval`` to document return status
  codes.
* Do not write documentation for trivial functions.
* Do not repeat documentation, use ``@see`` for example.
* Do not use ``@note``.
* Use groups and arrange them in a hierarchy. Put every file into at least
  one group.
* Use dot comments for state diagrams.
* Use one whitespace character after an asterisk.

Special Notes for Google Code-in Students
-----------------------------------------

Follow the directions given by the `Google Code-in
<https://devel.rtems.org/wiki/GCI>`_ task and this should take
care of itself if in doubt ask a mentor and/or tell a mentor the decision you
made.

Header File Example
-------------------

`thread.h
<https://git.rtems.org/rtems/tree/cpukit/include/rtems/score/thread.h>`_ and
`threadimpl.h
<https://git.rtems.org/rtems/tree/cpukit/include/rtems/score/threadimpl.h>`_
should be a good example of how a header file shouldbe written. The following
gives details in bits and pieces.

Header blocks
-------------

Header files should contain the similar comment blocks as other source files,
described at :ref:`coding-file-hdr`.

.. code-block:: c

  /**
   * @file
   *
   * @ingroup FlipFlop
   *
   * @brief Flip-Flop API
   */

  /*
   * Copyright (c) YYYY Author.
   *
   * The license and distribution terms for this file may be
   * found in the file LICENSE in this distribution or at
   * http://www.rtems.com/license/LICENSE.
   */

Header guard
------------

After the comment blocks, use a header guard that assembles at least the
include path of the file. For example, if ``flipflop.h`` is in
``<rtems/lib/flipflop.h>`` then

.. code-block:: c

  #ifndef RTEMS_LIB_FLIP_FLOP_H
  #define RTEMS_LIB_FLIP_FLOP_H

Includes
--------

Then add your include files before protecting C declarations from C++.

.. code-block:: c

  #include <rtems.h>

  #ifdef __cplusplus
  extern "C" {
  #endif /* __cplusplus */

Using @defgroup for group definitions
-------------------------------------

Add any group definitions surrounding the function declarations that belong
in that group. Rarely, a header may define more than one group. Here we use
a dot diagram.

.. code-block:: c

  /**
   * @defgroup FlipFlop Flip-Flop
   *
   * @brief Simple Flip-Flop state machine.
   *
   * @dot
   *   digraph {
   *     start [label="START"];
   *     flip [label="FLIP"];
   *     flop [label="FLOP"];
   *     flip -> flop [label="flop()", URL="\ref flop"];
   *     flop -> flip [label="flip()", URL="\ref flip"];
   *     start -> flip
   *       [label="flip_flop_initialize(FLIP)", URL="\ref flip_flop_initialize"];
   *     start -> flop
   *       [label="flip_flop_initialize(FLOP)", URL="\ref flip_flop_initialize"];
   *     flip -> start
   *       [label="flip_flop_restart()", URL="\ref flip_flop_restart"];
   *   }
   * @enddot
   *
   * @{
   */

enum and struct
---------------

Provide documentation for declarations of enumerated types and structs.
Use typedefs for structs, and do not use ``_t`` as a typename suffix.

.. code-block:: c

  /**
   * @brief The set of possible flip-flop states.
   *
   * Enumerated type to define the set of states for a flip-flop.
   */
  typedef enum {
    START = 0,
    FLIP,
    FLOP
  } flip_flop_state;

  /**
   * @brief Object containing multiple flip-flops.
   *
   * Encapsulates multiple flip-flops.
   */
  typedef struct {
    /**
     * @brief Primary flip-flop.
     */
    flip_flop_state primary;
    /**
     * @brief Secondary flip-flop.
     */
    flip_flop_state secondary;
  } flip_flop_multiple;

Using @name for organization
----------------------------

Complicated groups can be given additional organization by using ``@name``, or
by declaring additional groups within the hierarchy of the header file's
top-level group.

.. code-block:: c

  /**
   * @name Flip-Flop Maintenance
   *
   * @{
   */

Declaring functions
-------------------

Function declarations should have an @brief that states what the function does
in a single topic sentence starting with a descriptive verb in the present
tense.

.. code-block:: c

  /**
   * @brief Initializes the flip-flop state.
   *
   * @param[in] state The initial state to set the flip-flop.
   *
   * @retval RTEMS_SUCCESSFUL Successfully initialized.
   * @retval RTEMS_INCORRECT_STATE Flip-flop state is not valid.
   */
  rtems_status_code flip_flop_initialize(flip_flop_state state);

  /**
   * @brief Restarts the flip-flop.
   *
   * @retval RTEMS_SUCCESSFUL Successfully restarted.
   * @retval RTEMS_INCORRECT_STATE Flip-flop not in flip state.
   */
  rtems_status_code flip_flop_restart(void);

Do not document trivial functions, such as getter/setter methods.

.. code-block:: c

  flip_flop_state flip_flop_current_state(void);

Close the documentation name definition and open a new name definition.

.. code-block:: c

  /** @} */

  /**
   * @name Flip-Flop Usage
   *
   * @{
   */

  /**
   * @brief Flip operation.
   *
   * @retval RTEMS_SUCCESSFUL Flipped successfully.
   * @retval RTEMS_INCORRECT_STATE Incorrect state for flip operation.
   */
  rtems_status_code flip( void );

  /**
   * @brief Flop operation.
   *
   * @retval RTEMS_SUCCESSFUL Flopped successfully.
   * @retval RTEMS_INCORRECT_STATE Incorrect state for flop operation.
   */
  rtems_status_code flop( void );

  /** @} */

Ending the file
---------------

Close the documentation group definition, then the extern C declarations,
then the header guard.

.. code-block:: c

  /** @} */

  #ifdef __cplusplus
  }
  #endif /* __cplusplus */

  #endif /* RTEMS_LIB_FLIP_FLOP_H */

 No newline at the end of the file.

Source File Example
-------------------

.. code-block:: c

  /**
   * @file
   *
   * @ingroup FlipFlop
   *
   * @brief Flip-Flop implementation.
   */

  /*
   * Copyright (c) YYYY Author.
   *
   * The license and distribution terms for this file may be
   * found in the file LICENSE in this distribution or at
   * http://www.rtems.com/license/LICENSE.
   */

  #include <rtems/lib/flipflop.h>

  static flip_flop_state current_state;

  rtems_status_code flip_flop_initialize(flip_flop_state state)
  {
    if (current_state == START) {
      current_state = state;

      return RTEMS_SUCCESSFUL;
    } else {
      return RTEMS_INCORRECT_STATE;
    }
  }

  rtems_status_code flip_flop_restart(void)
  {
    if (current_state == FLIP) {
      current_state = START;

      return RTEMS_SUCCESSFUL;
    } else {
      return RTEMS_INCORRECT_STATE;
    }
  }

  flip_flop_state flip_flop_current_state(void)
  {
    return current_state;
  }

  rtems_status_code flip(void)
  {
    if (current_state == FLOP) {
      current_state = FLIP;

      return RTEMS_SUCCESSFUL;
    } else {
      return RTEMS_INCORRECT_STATE;
    }
  }

  rtems_status_code flop(void)
  {
    if (current_state == FLIP) {
      current_state = FLOP;

      return RTEMS_SUCCESSFUL;
    } else {
      return RTEMS_INCORRECT_STATE;
    }
  }

Files
-----
Document files with the ``@file`` directive omitting the optional filename
argument. Doxygen will infer the filename from the actual name of the file.
Within one Doxygen run all files are unique and specified by the current
Doxyfile. We can define how the generated output of path and filenames looks
like in the Doxyfile via the ``FULL_PATH_NAMES``, ``STRIP_FROM_PATH`` and
``STRIP_FROM_INC_PATH`` options.

Functions
---------

For documentation of function arguments there are basically to ways:

The first one uses ``@param``:

.. code-block:: c

  /**
   * @brief Copies from a source to a destination memory area.
   *
   * The source and destination areas may not overlap.
   *
   * @param[out] dest The destination memory area to copy to.
   * @param[in] src The source memory area to copy from.
   * @param[in] n The number of bytes to copy.
   */

The second is to use ``@a`` param in descriptive text, for example:

.. code-block:: c

  /**
  * Copies @a n bytes from a source memory area @a src to a destination memory
  * area @a dest, where both areas may not overlap.
  */

The ``@a`` indicates that the next word is a function argument and deserves
some kind of highlighting. However, we feel that ``@a`` buries the usage of
function arguments within description text. In RTEMS sources, we prefer to
use ``@param`` instead of ``@a``.

Doxyfile Hints
--------------

Header Files
~~~~~~~~~~~

It is an RTEMS build feature that header files need to be installed in order to
be useful. One workaround to generate documentation which allows automatic
link generation is to use the installed header files as documentation input.
Assume that we have the RTEMS sources in the rtems directory and the build of
our BSP in build/powerpc-rtems5/mybsp relative to a common top-level directory.
Then you can configure Doxygen like:

.. code-block::

  INPUT           = rtems/bsps/powerpc/mybsp \
                    rtems/c/src/lib/libcpu/powerpc/mycpu \
                    rtems/make/custom/mybsp.cfg \
                    build/powerpc-rtems5/mybsp/lib/include/myincludes

  RECURSIVE       = YES

  EXCLUDE         = rtems/bsps/powerpc/mybsp/include \
                    rtems/c/src/lib/libcpu/powerpc/mycpu/include

  FULL_PATH_NAMES = YES

  STRIP_FROM_PATH = build/powerpc-rtems5/mybsp/lib/include \
                    rtems

Script and Assembly Files
~~~~~~~~~~~~~~~~~~~~~~~~~

Doxygen cannot cope with script (= files with #-like comments) or assembly
files. But you can add filter programs for them

.. COMMENT: TBD - Add source code for filter programs somewhere

.. code-block::

  FILTER_PATTERNS = *.S=c-comments-only \
                    *.s=c-comments-only \
                    *.cfg=script-comments-only \
                    *.am=script-comments-only \
                    *.ac=script-comments-only

Assembly Example
~~~~~~~~~~~~~~~~

.. code-block:: c

  /**
   * @fn void mpc55xx_fmpll_reset_config()
   *
   * @brief Configure FMPLL after reset.
   *
   * Sets the system clock from 12 MHz in two steps up to 128 MHz.
   */
  GLOBAL_FUNCTION mpc55xx_fmpll_reset_config
      /* Save link register */
      mflr r3

      LA r4, FMPLL_SYNCR

You have to put a declaration of this function somewhere in a header file.

Script Example
~~~~~~~~~~~~~~

.. code-block:: shell

  ##
  #
  # @file
  #
  # @ingroup mpc55xx_config
  #
  # @brief Configure script of LibBSP for the MPC55xx evaluation boards.
  #

  AC_PREREQ([2.69])
  AC_INIT([rtems-c-src-lib-libbsp-powerpc-mpc55xxevb],[_RTEMS_VERSION],[https://devel.rtems.org/newticket])


GCC Attributes
--------------

The Doxygen C/C++ parser cannot cope with the GCC ``attribute((something))``
stuff. But you can discard such features with pre-defined preprocessor macros

.. code-block:: shell

  ENABLE_PREPROCESSING = YES
  MACRO_EXPANSION      = YES
  EXPAND_ONLY_PREDEF   = YES
  PREDEFINED           = __attribute__(x)=