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

[Kieran Bingham]

Hi Laurent,

On 08/01/2019 14:43, Laurent Pinchart wrote:
> 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.

Lets drop this patch for now.

I'll submit a patch next to quieten the sphinx build, then consider this
topic complete for the moment.

--
Kieran


> 
>>  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
--
Kieran