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 +++++++++++++++++++++++++++++++++++++ eng/coding-doxygen.rst | 2 ++ eng/coding-file-hdr.rst | 2 ++ 3 files changed, 41 insertions(+) (limited to 'eng') 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 -------- 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 -------------------------- -- cgit v1.2.3