[rtems-docs commit] eng: Clarify "Source Documentation" section

[Sebastian Huber]

Module:    rtems-docs
Branch:    master
Commit:    dc345cf7fdbfec32602a2febcb884c93ce58cd02
Changeset: http://git.rtems.org/rtems-docs/commit/?id=dc345cf7fdbfec32602a2febcb884c93ce58cd02

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Thu Nov  5 19:38:12 2020 +0100

eng: Clarify "Source Documentation" section

---

 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
 ==============