[PATCH v5 04/18] libcamera: Mark internal parts of public classes with \internal

[Dan Scally]

Hi Laurent

On 05/08/2024 15:36, Laurent Pinchart wrote:
> The libcamera public API exposes classes that have parts considered
> internal. They inherit the Extensible class, and their internal parts
> are split into a Private class. Those classes are defined in public API
> headers, and their Private counterparts are defined in internal headers
> sharing a common file name (in a different directory). Both headers are
> documented in the same source file.
>
> For instance, include/libcamera/camera.h contains the public API of the
> Camera class, and include/libcamera/internal/camera.h its internal
> counterpart. Both are documented in src/libcamera/camera.cpp.
>
> As the internal headers are not part of the public API, they need to be
> hidden from the future public API builds. To prepare for doing so, mark
> them with the \internal Doxygen directive. Hardcode the Doxygen
> INTERNAL_DOCS option to YES to include the internal API. This will be
> changed later for the public API documentation build.
>
> Signed-off-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
> ---


Reviewed-by: Daniel Scally <dan.scally at ideasonboard.com>

>   Documentation/Doxyfile.in        | 1 +
>   src/libcamera/camera.cpp         | 1 +
>   src/libcamera/camera_manager.cpp | 1 +
>   src/libcamera/framebuffer.cpp    | 5 ++++-
>   src/libcamera/request.cpp        | 1 +
>   5 files changed, 8 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/Doxyfile.in b/Documentation/Doxyfile.in
> index abafcf6c6c66..62e63968ce62 100644
> --- a/Documentation/Doxyfile.in
> +++ b/Documentation/Doxyfile.in
> @@ -17,6 +17,7 @@ EXTENSION_MAPPING      = h=C++
>   
>   TOC_INCLUDE_HEADINGS   = 0
>   
> +INTERNAL_DOCS          = YES
>   CASE_SENSE_NAMES       = YES
>   
>   QUIET                  = YES
> diff --git a/src/libcamera/camera.cpp b/src/libcamera/camera.cpp
> index f89510ea0472..3c8f30d54401 100644
> --- a/src/libcamera/camera.cpp
> +++ b/src/libcamera/camera.cpp
> @@ -118,6 +118,7 @@
>    */
>   
>   /**
> + * \internal
>    * \file libcamera/internal/camera.h
>    * \brief Internal camera device handling
>    */
> diff --git a/src/libcamera/camera_manager.cpp b/src/libcamera/camera_manager.cpp
> index 95a9e3264526..5a21132a08c2 100644
> --- a/src/libcamera/camera_manager.cpp
> +++ b/src/libcamera/camera_manager.cpp
> @@ -23,6 +23,7 @@
>    */
>   
>   /**
> + * \internal
>    * \file libcamera/internal/camera_manager.h
>    * \brief Internal camera manager support
>    */
> diff --git a/src/libcamera/framebuffer.cpp b/src/libcamera/framebuffer.cpp
> index 63d679cb504d..f39db1223432 100644
> --- a/src/libcamera/framebuffer.cpp
> +++ b/src/libcamera/framebuffer.cpp
> @@ -16,7 +16,10 @@
>   /**
>    * \file libcamera/framebuffer.h
>    * \brief Frame buffer handling
> - *
> + */
> +
> +/**
> + * \internal
>    * \file libcamera/internal/framebuffer.h
>    * \brief Internal frame buffer handling support
>    */
> diff --git a/src/libcamera/request.cpp b/src/libcamera/request.cpp
> index fdf12c1e9088..24fa3a57312e 100644
> --- a/src/libcamera/request.cpp
> +++ b/src/libcamera/request.cpp
> @@ -29,6 +29,7 @@
>    */
>   
>   /**
> + * \internal
>    * \file libcamera/internal/request.h
>    * \brief Internal support for request handling
>    */