summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLaurent Pinchart <laurent.pinchart@ideasonboard.com>2019-10-23 16:23:47 +0300
committerLaurent Pinchart <laurent.pinchart@ideasonboard.com>2019-10-23 17:07:03 +0300
commitc98407bb2fdb58d2d0f66f96904661a628d4a3af (patch)
treeb7474900bacd97c2f4dcddcd7638f7f24d6d3312
parent408c98ea456a63e3820fe264039a0ff240984372 (diff)
Documentation: coding-style: Document usage of C compatibility headers
The C++ standard defines a set of C++ standard library headers, and for some of them, defines C compatibility headers. The former have a name of the form <cxxx> while the later are named <xxx.h>. The C++ headers declare names in the std namespace, and may declare the same names in the global namespace. The C compatibility headers declare names in the global namespace, and may declare the same names in the std namespace. We want to standardise on one set of headers through libcamera, and don't want to rely on optional behaviour. We can thus either use the C++ headers with an explicit std:: namespace qualifier through the code, or the C headers without the qualifier. Both set of headers are defined by the C++ standard, and are thus valid choices. After weighing pros and cons, we have decided to use the C compatibility headers, as nobody wanted to write std::uint32_t. Document this decision. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com> Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
-rw-r--r--Documentation/coding-style.rst12
1 files changed, 12 insertions, 0 deletions
diff --git a/Documentation/coding-style.rst b/Documentation/coding-style.rst
index 8dd1afce..ced31551 100644
--- a/Documentation/coding-style.rst
+++ b/Documentation/coding-style.rst
@@ -170,6 +170,18 @@ These rules match the `object ownership rules from the Chromium C++ Style Guide`
long term borrowing isn't marked through language constructs, it shall be
documented explicitly in details in the API.
+C Compatibility Headers
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The C++ standard defines a set of C++ standard library headers, and for some of
+them, defines C compatibility headers. The former have a name of the form
+<cxxx> while the later are named <xxx.h>. The C++ headers declare names in the
+std namespace, and may declare the same names in the global namespace. The C
+compatibility headers declare names in the global namespace, and may declare
+the same names in the std namespace. Usage of the C compatibility headers is
+strongly preferred. Code shall not rely on the optional declaration of names in
+the global or std namespace.
+
Documentation
-------------