From c694df13308534992e90b761827af53ae2663654 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Thu, 5 Nov 2020 19:24:24 +0100 Subject: eng: Add header file conventions --- eng/coding-conventions.rst | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) (limited to 'eng/coding-conventions.rst') 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 ``, ``#include ``, + ``#include ``, 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 -------- -- cgit v1.2.3