diff options
author | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2020-11-05 19:38:12 +0100 |
---|---|---|
committer | Sebastian Huber <sebastian.huber@embedded-brains.de> | 2020-11-11 07:43:38 +0100 |
commit | dc345cf7fdbfec32602a2febcb884c93ce58cd02 (patch) | |
tree | 19de22af99bb18fbe44163003cbd4a19f2a53efa | |
parent | eng: Add header file conventions (diff) | |
download | rtems-docs-dc345cf7fdbfec32602a2febcb884c93ce58cd02.tar.bz2 |
eng: Clarify "Source Documentation" section
-rw-r--r-- | eng/coding-conventions.rst | 27 | ||||
-rw-r--r-- | eng/coding-file-hdr.rst | 2 |
2 files changed, 19 insertions, 10 deletions
diff --git a/eng/coding-conventions.rst b/eng/coding-conventions.rst index e7a67ec..5dd8df5 100644 --- a/eng/coding-conventions.rst +++ b/eng/coding-conventions.rst @@ -18,17 +18,24 @@ for examples that illustrate style rules and Doxygen usage. Source Documentation -------------------- -* Use Doxygen according to our `Doxygen Recommendations <https://devel.rtems.org/wiki/Developer/Coding/Doxygen>`_.. -* Start each file with a brief description followed by a license. - See `Boilerplate File Header <https://devel.rtems.org/wiki/Developer/Coding/Boilerplate_File_Header>`_.. +* Use Doxygen according to our :ref:`DoxygenGuidelines`. + +* Use the file templates, see :ref:`FileTemplates`. + * Use ``/* */`` comments. -* Use comments wisely within function bodies, to explain - or draw attention without being verbose. -* Use English prose and strive for good grammar, - spelling, and punctuation. -* Use TODO: with a comment to indicate code that needs improvement. - Make it clear what there is to do. -* Use XXX or FIXME to indicate an error/bug/broken code. + +* Do not use ``//`` comments. + +* Use comments wisely within function bodies, to explain or draw attention + without being verbose. + +* Use English prose and strive for good grammar, spelling, and punctuation. + +* Use ``TODO`` with a comment to indicate code that needs improvement. Make + it clear what there is to do. Add a ticket and add a link to it. + +* Use ``XXX`` or ``FIXME`` to indicate an error/bug/broken code. Add a ticket + and add a link to it. Licenses -------- diff --git a/eng/coding-file-hdr.rst b/eng/coding-file-hdr.rst index 053e01e..caac2f7 100644 --- a/eng/coding-file-hdr.rst +++ b/eng/coding-file-hdr.rst @@ -3,6 +3,8 @@ .. Copyright (C) 2018, 2020 embedded brains GmbH (http://www.embedded-brains.de) .. Copyright (C) 2018, 2020 Sebastian Huber +.. _FileTemplates: + File Templates ============== |