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

[Kieran Bingham]

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 at ideasonboard.com>

Reviewed-by: Kieran Bingham <kieran.bingham at 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
>  -------------
> 

-- 
Regards
--
Kieran