[libcamera-devel,1/4] Documentation: coding-style: Document usage of C compatibility headers

2211 diff mbox series

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 weighting 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>
---
 Documentation/coding-style.rst | 12 ++++++++++++
 1 file changed, 12 insertions(+)

Hi Laurent,

On 23/10/2019 14:52, Laurent Pinchart wrote:
> 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 weighting pros and cons, we have decided to use the C

s/weighting/weighing/ :-D

> compatibility headers, as nobody wanted to write std::uint32_t. Document
> this decision.

Sounds good to me.

> 
> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>

> ---
>  Documentation/coding-style.rst | 12 ++++++++++++
>  1 file changed, 12 insertions(+)
> 
> diff --git a/Documentation/coding-style.rst b/Documentation/coding-style.rst
> index 8dd1afce1a2c..ced3155169a6 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.
> +

Is this an intentional double blank line ?

>  
>  Documentation
>  -------------
>

Hi Laurent,

Thanks for your work.

For all of the patches in this series,

Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>

On 2019-10-23 16:52:55 +0300, Laurent Pinchart wrote:
> 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 weighting 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>
> ---
>  Documentation/coding-style.rst | 12 ++++++++++++
>  1 file changed, 12 insertions(+)
> 
> diff --git a/Documentation/coding-style.rst b/Documentation/coding-style.rst
> index 8dd1afce1a2c..ced3155169a6 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
>  -------------
> -- 
> Regards,
> 
> Laurent Pinchart
> 
> _______________________________________________
> libcamera-devel mailing list
> libcamera-devel@lists.libcamera.org
> https://lists.libcamera.org/listinfo/libcamera-devel