| .. _files: |
| |
| 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: |