[PATCH 3/4] eng: Clarify "Source Documentation" section

Sebastian Huber sebastian.huber at embedded-brains.de
Thu Nov 5 18:43:19 UTC 2020


---
 eng/coding-conventions.rst | 27 +++++++++++++++++----------
 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
 ==============
 
-- 
2.26.2



More information about the devel mailing list