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

[Laurent Pinchart]

Hi Jacopo,

On Thu, Jul 29, 2021 at 10:05:42PM +0200, Jacopo Mondi wrote:
> 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" :)

The issue is that the Extensible::_d() function isn't meant to be called
directly, but I haven't found a way to get doxygen to document the
overridden functions generated by LIBCAMERA_DECLARE_PRIVATE(). I've thus
decided to document this in the base Extensible::_d() function as the
best workaround I could find :-S.

> Reviewed-by: Jacopo Mondi <jacopo at jmondi.org>
> 
> > + *
> > + * \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