[libcamera-devel] [PATCH 2/2] [RFC] Documentation: Enable parameter documentation warnings

[Laurent Pinchart]

Hi Kieran,

Thank you for the patch.

On Tuesday, 8 January 2019 15:21:06 EET Kieran Bingham wrote:
> Enable WARN_NO_PARAMDOC to guide us towards more complete documentation.
> 
> Signed-off-by: Kieran Bingham <kieran.bingham at ideasonboard.com>
> 
> ---
> This currently generates the following extra warnings:
> 
>   src/libcamera/pipeline/vimc.cpp:17: warning: Compound
> libcamera::PipeHandlerVimc is not documented.
> include/libcamera/camera_manager.h:20: warning: Compound
> libcamera::CameraManager is not documented.
> src/libcamera/include/device_enumerator.h:37: warning: return type of
> member libcamera::DeviceEnumerator::create is not documented
> src/libcamera/include/log.h:26: warning: parameters of member
> libcamera::LogMessage::LogMessage are not (all) documented
> src/libcamera/include/log.h:24: warning: parameters of member
> libcamera::LogMessage::LogMessage are not (all) documented
> src/libcamera/include/log.h:29: warning: return type of member
> libcamera::LogMessage::stream is not documented
> src/libcamera/include/media_object.h:94: warning: parameters of member
> libcamera::MediaEntity::MediaDevice are not (all) documented
> src/libcamera/include/media_object.h:43: warning: parameters of member
> libcamera::MediaLink::MediaDevice are not (all) documented
> src/libcamera/include/media_object.h:27: warning: parameters of member
> libcamera::MediaObject::MediaDevice are not (all) documented
> src/libcamera/include/media_object.h:66: warning: parameters of member
> libcamera::MediaPad::MediaDevice are not (all) documented
> src/libcamera/pipeline/vimc.cpp:22: warning: parameters of member
> libcamera::PipeHandlerVimc::match are not (all) documented
> src/libcamera/include/pipeline_handler.h:25: warning: parameters of member
> libcamera::PipelineHandler::match are not (all) documented

I think this is generally useful, but only if we can document all parameters. 
I had a quick look, and we get a warning for

	LogMessage(const LogMessage&) = delete;

We also get warnings for

	friend class MediaDevice;

in media_object.h.

Unless we can instruct doxygen to ignore these, I don't think we should enable 
parameter warnings by default as we wouldn't be able to achieve a clean build.

>  Documentation/Doxyfile.in | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/Doxyfile.in b/Documentation/Doxyfile.in
> index 335664dbcbf0..9dfab0852a9d 100644
> --- a/Documentation/Doxyfile.in
> +++ b/Documentation/Doxyfile.in
> @@ -757,7 +757,7 @@ WARN_IF_DOC_ERROR      = YES
>  # parameter documentation, but not about the absence of documentation.
>  # The default value is: NO.
> 
> -WARN_NO_PARAMDOC       = NO
> +WARN_NO_PARAMDOC       = YES
> 
>  # If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop
> when # a warning is encountered.

-- 
Regards,

Laurent Pinchart