mirror of
https://github.com/zephyrproject-rtos/zephyr
synced 2025-09-13 06:51:56 +00:00
308f1586d6
This commit set back .S as the assembly code extension for Kbuild. Change-Id: Ib0119876bd0bed6617bbfbad2ca6a44e172ab042 Signed-off-by: Juan Manuel Cruz <juan.m.cruz.alcaraz@linux.intel.com>
59 lines
1.4 KiB
ReStructuredText
59 lines
1.4 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 contents of
|
|
the file. 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. Please refer to the
|
|
`Doxygen documentation`_ for further 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:
|