mirror of
https://git.rtems.org/rtems-docs/
synced 2025-05-15 07:16:37 +08:00
eng/coding-doxygen: Fix errors
This work was part of GCI 2018.
This commit is contained in:
Marçal Comajoan Cara
Joel Sherrill
parent
b8b4f14973
commit
cc826d74f3
@ -4,10 +4,10 @@
|
||||
.. COMMENT: RTEMS Foundation, The RTEMS Documentation Project
|
||||
|
||||
General Doxygen Recommentations
|
||||
-------------------------------
|
||||
===============================
|
||||
|
||||
TBD - Convert the following to Rest and insert into this file
|
||||
TBD - https://devel.rtems.org/wiki/Developer/Coding/Doxygen
|
||||
.. COMMENT: TBD - Convert the following to Rest and insert into this file
|
||||
.. COMMENT: TBD - https://devel.rtems.org/wiki/Developer/Coding/Doxygen
|
||||
|
||||
.. sidebar:: *History*
|
||||
|
||||
@ -23,39 +23,42 @@ TBD - https://devel.rtems.org/wiki/Developer/Coding/Doxygen
|
||||
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 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.
|
||||
* 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
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
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.
|
||||
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
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
-------------------
|
||||
|
||||
The files *thread.h*
|
||||
(https://git.rtems.org/rtems/tree/cpukit/score/include/rtems/score/thread.h)
|
||||
and *threadimpl.h*
|
||||
(https://git.rtems.org/rtems/tree/cpukit/score/include/rtems/score/threadimpl.h)
|
||||
should be a good example of how a header file should be written. The
|
||||
following gives details in bits and pieces.
|
||||
`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 `Boilerplate File Header <https://devel.rtems.org/wiki/Developer/Coding/Boilerplate_File_Header>`_.
|
||||
Header files should contain the similar comment blocks as other source files,
|
||||
described at :ref:`coding-file-hdr`.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
@ -75,12 +78,12 @@ Header files should contain the similar comment blocks as other source files, de
|
||||
* http://www.rtems.com/license/LICENSE.
|
||||
*/
|
||||
|
||||
Header Guard
|
||||
^^^^^^^^^^^^
|
||||
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
|
||||
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
|
||||
|
||||
@ -88,11 +91,10 @@ least the include path of the file. For example, if flipflop.h is in
|
||||
#define RTEMS_LIB_FLIP_FLOP_H
|
||||
|
||||
Includes
|
||||
^^^^^^^^
|
||||
--------
|
||||
|
||||
Then add your include files before protecting C declarations from C++.
|
||||
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#include <rtems.h>
|
||||
@ -102,12 +104,11 @@ Then add your include files before protecting C declarations from 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.
|
||||
-------------------------------------
|
||||
|
||||
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
|
||||
|
||||
@ -136,11 +137,10 @@ group. Here we use a dot diagram.
|
||||
*/
|
||||
|
||||
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.
|
||||
---------------
|
||||
|
||||
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
|
||||
|
||||
@ -171,13 +171,12 @@ structs. Use typedefs for structs, and do not use _t as a typename suffix.
|
||||
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.
|
||||
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
|
||||
|
||||
@ -188,12 +187,11 @@ file's top-level group.
|
||||
*/
|
||||
|
||||
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.
|
||||
-------------------
|
||||
|
||||
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
|
||||
|
||||
@ -252,7 +250,7 @@ Close the documentation name definition and open a new name definition.
|
||||
/** @} */
|
||||
|
||||
Ending the file
|
||||
^^^^^^^^^^^^^^^
|
||||
---------------
|
||||
|
||||
Close the documentation group definition, then the extern C declarations,
|
||||
then the header guard.
|
||||
@ -270,7 +268,7 @@ then the header guard.
|
||||
No newline at the end of the file.
|
||||
|
||||
Source File Example
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
-------------------
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
@ -344,16 +342,22 @@ Source File Example
|
||||
}
|
||||
|
||||
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.
|
||||
-----
|
||||
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:
|
||||
For documentation of function arguments there are basically to ways:
|
||||
|
||||
.. code-block::
|
||||
The first one uses ``@param``:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
/**
|
||||
* @brief Copies from a source to a destination memory area.
|
||||
@ -364,30 +368,33 @@ For documentation of function arguments there are basically to ways: The first o
|
||||
* @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:
|
||||
|
||||
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.
|
||||
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
|
||||
------------
|
||||
|
||||
TBD - This is out of date since the include file reorganizaiton
|
||||
|
||||
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:
|
||||
~~~~~~~~~~~
|
||||
|
||||
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::
|
||||
|
||||
@ -407,11 +414,12 @@ to a common top-level directory. Then you can configure Doxygen like:
|
||||
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 (TODO: Add source code
|
||||
for filter programs somewhere):
|
||||
files. But you can add filter programs for them
|
||||
|
||||
.. COMMENT: TBD - Add source code for filter programs somewhere
|
||||
|
||||
.. code-block::
|
||||
|
||||
@ -422,9 +430,9 @@ for filter programs somewhere):
|
||||
*.ac=script-comments-only
|
||||
|
||||
Assembly Example
|
||||
^^^^^^^^^^^^^^^^
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block::
|
||||
.. code-block:: c
|
||||
|
||||
/**
|
||||
* @fn void mpc55xx_fmpll_reset_config()
|
||||
@ -442,7 +450,7 @@ Assembly Example
|
||||
You have to put a declaration of this function somewhere in a header file.
|
||||
|
||||
Script Example
|
||||
^^^^^^^^^^^^^^
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
@ -455,15 +463,15 @@ Script Example
|
||||
# @brief Configure script of LibBSP for the MPC55xx evaluation boards.
|
||||
#
|
||||
|
||||
AC_PREREQ(2.60)
|
||||
AC_INIT([rtems-c-src-lib-libbsp-powerpc-mpc55xxevb],[_RTEMS_VERSION],[http://www.rtems.org/bugzilla])
|
||||
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:
|
||||
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
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user