[PATCH 2/4] eng: Add header file conventions
Sebastian Huber
sebastian.huber at embedded-brains.de
Thu Nov 5 18:43:18 UTC 2020
---
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
--------------------------
--
2.26.2
More information about the devel
mailing list