[libcamera-devel] [PATCH 4/5] libcamera: Document private members

[Niklas Söderlund]

Hi Jacopo,

Thanks for your work.

On 2019-01-03 18:38:58 +0100, Jacopo Mondi wrote:
> The newly added MediaDevice::setLink() function is defined as private,
> but it is worth being documented, as it is called from the friend method
> MediaLink::setup().
> 
> In the library code base, several private methods and fields are
> documented, but do not show up in the generated documentation output.
> Change doxygen settings to output processed documentation for the
> private fields and methods, when proper doxygen comments are applied to
> them (and do not complain if private members are not documented at all).

I would split this to a separate commit.

> 
> Signed-off-by: Jacopo Mondi <jacopo at jmondi.org>
> ---
>  Documentation/Doxyfile.in      |  4 ++--
>  src/libcamera/media_device.cpp | 22 ++++++++++++++++++++++
>  2 files changed, 24 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/Doxyfile.in b/Documentation/Doxyfile.in
> index b1a70d3..16dcccd 100644
> --- a/Documentation/Doxyfile.in
> +++ b/Documentation/Doxyfile.in
> @@ -442,7 +442,7 @@ EXTRACT_ALL            = NO
>  # be included in the documentation.
>  # The default value is: NO.
>  
> -EXTRACT_PRIVATE        = NO
> +EXTRACT_PRIVATE        = YES
>  
>  # If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal
>  # scope will be included in the documentation.
> @@ -487,7 +487,7 @@ EXTRACT_ANON_NSPACES   = NO
>  # section is generated. This option has no effect if EXTRACT_ALL is enabled.
>  # The default value is: NO.
>  
> -HIDE_UNDOC_MEMBERS     = NO
> +HIDE_UNDOC_MEMBERS     = YES
>  
>  # If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all
>  # undocumented classes that are normally visible in the class hierarchy. If set
> diff --git a/src/libcamera/media_device.cpp b/src/libcamera/media_device.cpp
> index b86d0c4..48aa805 100644
> --- a/src/libcamera/media_device.cpp
> +++ b/src/libcamera/media_device.cpp
> @@ -641,6 +641,28 @@ bool MediaDevice::populateLinks(const struct media_v2_topology &topology)
>  	return true;
>  }
>  
> +/**
> + * \brief Apply \a flags to a link between two pads
> + * \param source The source pad
> + * \param sink The sink pad
> + * \param flags The link flags
> + *
> + * Implements 'raw' link handling, as this functions applies \a flags,
> + * (whose only accepted values are the ones defined by the Media Controller
> + * APIs in MEDIA_LNK_FL_* macros) to a link between two pads. No correctness
> + * checks on the link existence and validity of \a flags is performed. The
> + * function assumes the \a source and \a sink pads are connected, and the
> + * supplied \a flags applies to the link (ie. immutable links cannot be
> + * disabled).
> + *
> + * This function wraps the raw MEDIA_IOC_SETUP_LINK ioctl, and shouldn't be
> + * called directly by any other class or method but the
> + * MediaLink::setup(bool enable) one, declared as friend for this reason.

I don't love this, make setLink() public :-)

> + *
> + * \sa MediaLink::setup(bool enable)
> + *
> + * \return 0 for success, negative error number otherwise
> + */
>  int MediaDevice::setLink(const MediaPad *source, const MediaPad *sink,
>  			 unsigned int flags)
>  {
> -- 
> 2.20.1
> 
> _______________________________________________
> libcamera-devel mailing list
> libcamera-devel at lists.libcamera.org
> https://lists.libcamera.org/listinfo/libcamera-devel

-- 
Regards,
Niklas Söderlund