[libcamera-devel] [RFC PATCH 01/17] libcamera: base: class: Document Extensible::_d() functions

[Jacopo Mondi]

Hi Laurent,

On Fri, Jul 23, 2021 at 07:00:20AM +0300, Laurent Pinchart wrote:
> The Extensible::_d() functions are meant to be called by users of the
> class. Document them.
>
> Signed-off-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
> ---
>  include/libcamera/base/class.h |  2 --
>  src/libcamera/base/class.cpp   | 17 +++++++++++++++++
>  2 files changed, 17 insertions(+), 2 deletions(-)
>
> diff --git a/include/libcamera/base/class.h b/include/libcamera/base/class.h
> index c2e1d3534ed1..9c7f0f2e6e27 100644
> --- a/include/libcamera/base/class.h
> +++ b/include/libcamera/base/class.h
> @@ -88,7 +88,6 @@ public:
>  	Extensible(Private *d);
>
>  protected:
> -#ifndef __DOXYGEN__
>  	template<typename T>
>  	const T *_d() const
>  	{
> @@ -100,7 +99,6 @@ protected:
>  	{
>  		return static_cast<T *>(d_.get());
>  	}
> -#endif
>
>  private:
>  	const std::unique_ptr<Private> d_;
> diff --git a/src/libcamera/base/class.cpp b/src/libcamera/base/class.cpp
> index 26b4967726d6..d0899671ca11 100644
> --- a/src/libcamera/base/class.cpp
> +++ b/src/libcamera/base/class.cpp
> @@ -150,6 +150,23 @@ Extensible::Extensible(Extensible::Private *d)
>  {
>  }
>
> +/**
> + * \fn Extensible::_d() const
> + * \brief Retrieve the private data instance
> + *
> + * This template function isn't meant to be called directly. Instead, classes
> + * derived from Extensible get, through the LIBCAMERA_DECLARE_PRIVATE() macro,
> + * overriden _d() functions that return the correct pointer type to the
> + * corresponding derived Private class.

It really took me a while to understand that we have Extensible::_d()
and the overriden versions, and it's written just here :)

Probably because the commit message says "are meant to be called by
users" and this starts with "isn't meant to be called directly" :)

Reviewed-by: Jacopo Mondi <jacopo at jmondi.org>

Thanks
  j

> + *
> + * \return A pointer to the private data instance
> + */
> +
> +/**
> + * \fn Extensible::_d()
> + * \copydoc Extensible::_d() const
> + */
> +
>  /**
>   * \var Extensible::d_
>   * \brief Pointer to the private data instance
> --
> Regards,
>
> Laurent Pinchart
>