[rtems-docs commit] eng: Add header file conventions

[Sebastian Huber]

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

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

eng: Add header file conventions

---

 eng/coding-conventions.rst | 37 +++++++++++++++++++++++++++++++++++++
 eng/coding-doxygen.rst     |  2 ++
 eng/coding-file-hdr.rst    |  2 ++
 3 files changed, 41 insertions(+)

diff --git a/eng/coding-conventions.rst b/eng/coding-conventions.rst
index b85d8fc..e7a67ec 100644
--- a/eng/coding-conventions.rst
+++ b/eng/coding-conventions.rst
@@ -251,6 +251,43 @@ Miscellaneous
 * If adding code to ''cpukit'' be sure the filename is unique since
   all files under that directory get merged into a single library.
 
+Header Files
+------------
+
+* Do not add top-level header files.  Place the header files in a directory,
+  for example ``#include <rtems/*>``, ``#include <bsp/*>``,
+  ``#include <dev/*>``, etc.
+
+* Use the extension :file:`.h` for C header files.
+
+* Use the extension :file:`.hpp` for C++ header files.
+
+* Use the file template for header files, see :ref:`CCXXHeaderFileTemplate`.
+
+* Use separate header files for the API and the implementation.
+
+* Use :file:`foobar.h` for the header file of the ``foobar`` module which
+  defines API components.
+
+* Use :file:`foobardata.h` for the header file of the ``foobar`` module which
+  defines interfaces used by the application configuration.
+
+* Use :file:`foobarimpl.h` for the header file of the ``foobar`` module which
+  defines interfaces, macros, and inline functions used by the implementation.
+
+* Do not place inline functions which are only used in one implementation
+  source file into the implementation header file.  Add these inline functions
+  directly to the corresponding source file.
+
+* Document all elements in header files with comments in Doxygen markup, see
+  :ref:`DoxygenGuidelines`.
+
+* Only place header files which should be directly included by the user with an
+  ``@file`` Doxygen directive into the API documentation group.  Place internal
+  API header files with an ``@file`` Doxygen command into the implementation
+  documentation group even if they define API elements.  The API documentation
+  group should only list public header files and no internal header files.
+
 Layering
 --------
 
diff --git a/eng/coding-doxygen.rst b/eng/coding-doxygen.rst
index 2f7682d..f4308ef 100644
--- a/eng/coding-doxygen.rst
+++ b/eng/coding-doxygen.rst
@@ -2,6 +2,8 @@
 
 .. Copyright (C) 2019 embedded brains GmbH
 
+.. _DoxygenGuidelines:
+
 Doxygen Guidelines
 ==================
 
diff --git a/eng/coding-file-hdr.rst b/eng/coding-file-hdr.rst
index 64eeec3..053e01e 100644
--- a/eng/coding-file-hdr.rst
+++ b/eng/coding-file-hdr.rst
@@ -72,6 +72,8 @@ Check the top-level :file:`COPYING` file of the repository.  If you are a new
 copyright holder, then add yourself to the top of the list.  If your last year
 of a substantial contribution changed, then please update your copyright line.
 
+.. _CCXXHeaderFileTemplate:
+
 C/C++ Header File Template
 --------------------------