rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-05-15 17:26:42 +08:00
Code Issues Packages Projects Releases Wiki Activity

eng/coding-doxygen.rst: Clean up and make subsubsections

Browse Source
This commit is contained in:
Joel Sherrill 2018-12-04 13:21:54 -06:00
parent cd6ac10478
commit f5c20a6ad8
1 changed files with 325 additions and 278 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

123
eng/coding-doxygen.rst
View File

@ -9,8 +9,21 @@ General Doxygen Recommentations
TBD - Convert the following to Rest and insert into this file TBD - Convert the following to Rest and insert into this file
TBD - https://devel.rtems.org/wiki/Developer/Coding/Doxygen 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 Doxygen Best Practices
---------------------- ^^^^^^^^^^^^^^^^^^^^^^
* Do not use @a. Instead use @param to document function parameters. * 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 @return. Instead use @retval to document return status codes.
@ -22,17 +35,25 @@ Doxygen Best Practices
* Use one whitespace character after an asterisk. * 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 Header File Example
------------------- ^^^^^^^^^^^^^^^^^^^
​`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. 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.
Header blocks 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 `Boilerplate File Header <https://devel.rtems.org/wiki/Developer/Coding/Boilerplate_File_Header>`_.
@ -54,10 +75,12 @@ Header files should contain the similar comment blocks as other source files, de
* http://www.rtems.com/license/LICENSE. * 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 .. code-block:: c
@ -65,7 +88,7 @@ After the comment blocks, use a header guard that assembles at least the include
#define RTEMS_LIB_FLIP_FLOP_H #define RTEMS_LIB_FLIP_FLOP_H
Includes Includes
-------- ^^^^^^^^
Then add your include files before protecting C declarations from C++. Then add your include files before protecting C declarations from C++.
@ -79,9 +102,11 @@ Then add your include files before protecting C declarations from C++.
#endif /* __cplusplus */ #endif /* __cplusplus */
Using @defgroup for group definitions 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 .. code-block:: c
@ -111,9 +136,10 @@ Add any group definitions surrounding the function declarations that belong in t
*/ */
enum and struct 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 .. code-block:: c
@ -147,9 +173,11 @@ Provide documentation for declarations of enumerated types and structs. Use type
Using @name for organization 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 .. code-block:: c
@ -160,12 +188,15 @@ Complicated groups can be given additional organization by using @name, or by de
*/ */
Declaring functions 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 .. code-block:: c
/** /**
* @brief Initializes the flip-flop state. * @brief Initializes the flip-flop state.
* *
@ -187,11 +218,13 @@ Function declarations should have an @brief that states what the function does i
Do not document trivial functions, such as getter/setter methods. Do not document trivial functions, such as getter/setter methods.
.. code-block:: c .. code-block:: c
flip_flop_state flip_flop_current_state(void); flip_flop_state flip_flop_current_state(void);
Close the documentation name definition and open a new name definition. Close the documentation name definition and open a new name definition.
.. code-block:: c .. code-block:: c
/** @} */ /** @} */
/** /**
@ -219,11 +252,13 @@ Close the documentation name definition and open a new name definition.
/** @} */ /** @} */
Ending the file Ending the file
--------------- ^^^^^^^^^^^^^^^
Close the documentation group definition, then the extern C declarations, then the header guard. Close the documentation group definition, then the extern C declarations,
then the header guard.
.. code-block:: c .. code-block:: c
/** @} */ /** @} */
#ifdef __cplusplus #ifdef __cplusplus
@ -235,7 +270,7 @@ Close the documentation group definition, then the extern C declarations, then t
No newline at the end of the file. No newline at the end of the file.
Source File Example Source File Example
------------------- ^^^^^^^^^^^^^^^^^^^
.. code-block:: c .. code-block:: c
@ -309,16 +344,17 @@ Source File Example
} }
Files 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 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: The first one uses @param:
.. code-block:: .. code-block::
/** /**
* @brief Copies from a source to a destination memory area. * @brief Copies from a source to a destination memory area.
* *
@ -338,15 +374,23 @@ For documentation of function arguments there are basically to ways: The first o
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 Doxyfile Hints
-------------- ^^^^^^^^^^^^^^
Header Files 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: 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:
.. code-block:: .. code-block::
INPUT = rtems/bsps/powerpc/mybsp \ INPUT = rtems/bsps/powerpc/mybsp \
rtems/c/src/lib/libcpu/powerpc/mycpu \ rtems/c/src/lib/libcpu/powerpc/mycpu \
rtems/make/custom/mybsp.cfg \ rtems/make/custom/mybsp.cfg \
@ -363,11 +407,14 @@ It is an RTEMS build feature that header files need to be installed in order to
rtems rtems
Script and Assembly Files 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): 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):
.. code-block:: .. code-block::
FILTER_PATTERNS = *.S=c-comments-only \ FILTER_PATTERNS = *.S=c-comments-only \
*.s=c-comments-only \ *.s=c-comments-only \
*.cfg=script-comments-only \ *.cfg=script-comments-only \
@ -375,9 +422,10 @@ Doxygen cannot cope with script (= files with #-like comments) or assembly files
*.ac=script-comments-only *.ac=script-comments-only
Assembly Example Assembly Example
---------------- ^^^^^^^^^^^^^^^^
.. code-block:: .. code-block::
/** /**
* @fn void mpc55xx_fmpll_reset_config() * @fn void mpc55xx_fmpll_reset_config()
* *
@ -394,9 +442,10 @@ Assembly Example
You have to put a declaration of this function somewhere in a header file. You have to put a declaration of this function somewhere in a header file.
Script Example Script Example
-------------- ^^^^^^^^^^^^^^
.. code-block:: shell
.. code-block::
## ##
# #
# @file # @file
@ -410,17 +459,15 @@ Script Example
AC_INIT([rtems-c-src-lib-libbsp-powerpc-mpc55xxevb],[_RTEMS_VERSION],[http://www.rtems.org/bugzilla]) AC_INIT([rtems-c-src-lib-libbsp-powerpc-mpc55xxevb],[_RTEMS_VERSION],[http://www.rtems.org/bugzilla])
GCC Attributes 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
.. code-block::
ENABLE_PREPROCESSING = YES ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES EXPAND_ONLY_PREDEF = YES
PREDEFINED = __attribute__(x)= PREDEFINED = __attribute__(x)=
History
-------
RTEMS is much older than ​`Doxygen <http://www.doxygen.org/>`_ and the documentation in the .h and .inl files was obviously not written with ​`Doxygen markup <http://www.stack.nl/~dimitri/doxygen/manual.html>`_. In 2007, `JoelSherrill <https://devel.rtems.org/wiki/TBR/User/JoelSherrill>`_ 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 RTEMSSuperCore is now built automatically multiple times per day and made available on the RTEMS Website. In April 2008, `JoelSherrill <https://devel.rtems.org/wiki/TBR/User/JoelSherrill>`_ began to update the Classic API (e.g. cpukit/rtems) .h and .inl files to include `​Doxygen markup <http://www.stack.nl/~dimitri/doxygen/manual.html>`_.