| Message ID | 20190108132106.24906-3-kieran.bingham@ideasonboard.com |
|---|---|
| State | Rejected |
| Headers | show |
| Series |
|
| Related | show |
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@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.
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@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. >
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.
Enable WARN_NO_PARAMDOC to guide us towards more complete documentation. Signed-off-by: Kieran Bingham <kieran.bingham@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 Documentation/Doxyfile.in | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)