58 lines
1.3 KiB
ReStructuredText
58 lines
1.3 KiB
ReStructuredText
.. _file_header_documentation:
|
|
|
|
File Header Documentation
|
|
#########################
|
|
|
|
Every .c, .h and .S file must contain a file header comment at the
|
|
beginning of the file. The file header must contain:
|
|
|
|
#. The filename. Use **@file** for Doxygen to auto-complete the
|
|
filename.
|
|
|
|
#. The brief description: A single line summarizing the file contents.
|
|
Use **@brief** to clearly mark the brief description.
|
|
|
|
#. The detailed description: One or multiple lines describing the
|
|
purpose of the file, how it works and any other pertinent
|
|
information such as copyrights, authors, etc.
|
|
|
|
.. note::
|
|
|
|
Doxygen has special commands for copyrights (@copyright), authors
|
|
(@author), and other important information. Refer to the
|
|
`Doxygen documentation`_ for details.
|
|
|
|
.. _Doxygen documentation:
|
|
http://www.stack.nl/~dimitri/doxygen/manual/index.html
|
|
|
|
Examples
|
|
********
|
|
|
|
Correct:
|
|
|
|
* A file header with a single line description.
|
|
|
|
.. literalinclude:: hello_commented.c
|
|
:language: c
|
|
:lines: 1-5
|
|
:emphasize-lines: 1,2,4
|
|
:linenos:
|
|
|
|
* A file header with a larger description.
|
|
|
|
.. literalinclude:: phil_task_commented.c
|
|
:language: c
|
|
:lines: 1-10
|
|
:emphasize-lines: 5-8
|
|
:linenos:
|
|
|
|
Incorrect:
|
|
|
|
A file header without a detailed description.
|
|
|
|
.. literalinclude:: phil_fiber_commented.c
|
|
:language: c
|
|
:lines: 1-3
|
|
:emphasize-lines: 4
|
|
:linenos:
|