[PATCH v5 05/18] libcamera: Hide *::Private classes with __DOXYGEN_PUBLIC__

[Dan Scally]

Hi Laurent

On 05/08/2024 15:36, Laurent Pinchart wrote:
> The *::Private classes are part of the internal API, as their name
> implies. They are defined in internal headers, but implemented in the
> same source file as their public counterparts. This will cause Doxygen
> to complain about missing class definition when splitting the public and
> internal API documents, as the internal headers won't be parsed by
> Doxygen for the public API documentation.
>
> Marking the classes with \internal isn't enough. The directive prevents
> the documentation block from being included in the output, but this
> occurs at the generation stage, after the documentation blocks are
> parsed. Fix this by completely hidding the implementation of the
> *::Private classes from Doxygen using preprocessor conditional
> compilation. To do so, introduce a new macro, __DOXYGEN_PUBLIC__, that
> will be defined for the public API documentation only.
>
> Signed-off-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>


This is fine too - I think I included them because I couldn't figure out a doxygen-only way of 
excluding them...but this way works.


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

> ---
>   src/libcamera/camera.cpp         | 2 ++
>   src/libcamera/camera_manager.cpp | 2 ++
>   src/libcamera/framebuffer.cpp    | 2 ++
>   src/libcamera/request.cpp        | 2 ++
>   4 files changed, 8 insertions(+)
>
> diff --git a/src/libcamera/camera.cpp b/src/libcamera/camera.cpp
> index 3c8f30d54401..aca466c9ba72 100644
> --- a/src/libcamera/camera.cpp
> +++ b/src/libcamera/camera.cpp
> @@ -565,6 +565,7 @@ CameraConfiguration::Status CameraConfiguration::validateColorSpaces(ColorSpaceF
>    * \brief The vector of stream configurations
>    */
>   
> +#ifndef __DOXYGEN_PUBLIC__
>   /**
>    * \class Camera::Private
>    * \brief Base class for camera private data
> @@ -725,6 +726,7 @@ void Camera::Private::setState(State state)
>   {
>   	state_.store(state, std::memory_order_release);
>   }
> +#endif /* __DOXYGEN_PUBLIC__ */
>   
>   /**
>    * \class Camera
> diff --git a/src/libcamera/camera_manager.cpp b/src/libcamera/camera_manager.cpp
> index 5a21132a08c2..fa44e33a135d 100644
> --- a/src/libcamera/camera_manager.cpp
> +++ b/src/libcamera/camera_manager.cpp
> @@ -35,6 +35,7 @@ namespace libcamera {
>   
>   LOG_DEFINE_CATEGORY(Camera)
>   
> +#ifndef __DOXYGEN_PUBLIC__
>   CameraManager::Private::Private()
>   	: initialized_(false)
>   {
> @@ -249,6 +250,7 @@ void CameraManager::Private::removeCamera(std::shared_ptr<Camera> camera)
>   	CameraManager *const o = LIBCAMERA_O_PTR();
>   	o->cameraRemoved.emit(camera);
>   }
> +#endif /* __DOXYGEN_PUBLIC__ */
>   
>   /**
>    * \class CameraManager
> diff --git a/src/libcamera/framebuffer.cpp b/src/libcamera/framebuffer.cpp
> index f39db1223432..826848f75a56 100644
> --- a/src/libcamera/framebuffer.cpp
> +++ b/src/libcamera/framebuffer.cpp
> @@ -107,6 +107,7 @@ LOG_DEFINE_CATEGORY(Buffer)
>    * \return The array of per-plane metadata
>    */
>   
> +#ifndef __DOXYGEN_PUBLIC__
>   /**
>    * \class FrameBuffer::Private
>    * \brief Base class for FrameBuffer private data
> @@ -209,6 +210,7 @@ FrameBuffer::Private::~Private()
>    * \brief Retrieve the dynamic metadata
>    * \return Dynamic metadata for the frame contained in the buffer
>    */
> +#endif /* __DOXYGEN_PUBLIC__ */
>   
>   /**
>    * \class FrameBuffer
> diff --git a/src/libcamera/request.cpp b/src/libcamera/request.cpp
> index 24fa3a57312e..8c56ed30d0c4 100644
> --- a/src/libcamera/request.cpp
> +++ b/src/libcamera/request.cpp
> @@ -38,6 +38,7 @@ namespace libcamera {
>   
>   LOG_DEFINE_CATEGORY(Request)
>   
> +#ifndef __DOXYGEN_PUBLIC__
>   /**
>    * \class Request::Private
>    * \brief Request private data
> @@ -306,6 +307,7 @@ void Request::Private::timeout()
>   
>   	emitPrepareCompleted();
>   }
> +#endif /* __DOXYGEN_PUBLIC__ */
>   
>   /**
>    * \enum Request::Status