[libcamera-devel] [PATCH] libcamera: request: Fix doxygen warning

[Laurent Pinchart]

Hi Umang,

Thank you for the patch.

On Tue, Aug 30, 2022 at 02:44:20PM +0530, Umang Jain via libcamera-devel wrote:
> Request::Private::reuse() uses \copydoc for its documentation being
> copied from Request::reuse(). However, both of these functions
> differs in function parameters aspect which causes doxygen to put out
> a warning:
> 
> libcamera::Request::Private::reuse has @param documentation sections but no arguments

I've justed updated doxygen and can indeed reproduce the problem.

> Currently doxygen has no helper section tag (like \copydetails) which
> can omit the \params and just the copy the body. So for now, copy the
> brief only with \copybrief to silence the warning.
> 
> Signed-off-by: Umang Jain <umang.jain at ideasonboard.com>
> ---
>  src/libcamera/request.cpp | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/src/libcamera/request.cpp b/src/libcamera/request.cpp
> index d2af1d22..42aa8483 100644
> --- a/src/libcamera/request.cpp
> +++ b/src/libcamera/request.cpp
> @@ -158,7 +158,7 @@ void Request::Private::cancel()
>  }
>  
>  /**
> - * \copydoc Request::reuse()
> + * \copybrief Request::reuse()
>   */

The Request::reuse() and Request::Private::reuse() functions are
different, the latter only resets the request but doesn't reuse
anything. How about using this as an opportunity to improve the code, by
renaming the function to reset() ? It could be documented as

/**
 * \brief Reset the request internal data to default values
 *
 * After calling this function, all request internal data will have default
 * values as if the Request::Private instance had just been constructed.
 */

The commit message needs a bit of an update.

Reviewed-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>

>  void Request::Private::reuse()
>  {

-- 
Regards,

Laurent Pinchart