[libcamera-devel] [PATCH 1/3] libcamera: Document documentation style and update the code accordingly
Laurent Pinchart
laurent.pinchart at ideasonboard.com
Fri Apr 19 12:21:53 CEST 2019
Hi Jacopo,
On Fri, Apr 19, 2019 at 10:40:56AM +0200, Jacopo Mondi wrote:
> On Thu, Apr 18, 2019 at 06:44:51PM +0300, Laurent Pinchart wrote:
> > The documentation style for the Doxygen comment blocks is inconsistent
> > in the library. Document the expectations and update all existing
> > comment blocks to match.
> >
> > Signed-off-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
> > ---
> > Documentation/coding-style.rst | 49 ++++++++++++++++++++++++++++
> > src/libcamera/camera.cpp | 9 -----
> > src/libcamera/camera_manager.cpp | 3 +-
> > src/libcamera/camera_sensor.cpp | 1 -
> > src/libcamera/device_enumerator.cpp | 4 +--
> > src/libcamera/event_dispatcher.cpp | 8 ++---
> > src/libcamera/event_notifier.cpp | 6 ++--
> > src/libcamera/geometry.cpp | 13 ++++----
> > src/libcamera/media_device.cpp | 35 ++++++++++----------
> > src/libcamera/media_object.cpp | 38 ++++++++++-----------
> > src/libcamera/pipeline/ipu3/ipu3.cpp | 10 ++----
> > src/libcamera/pipeline_handler.cpp | 5 ++-
> > src/libcamera/request.cpp | 1 -
> > src/libcamera/signal.cpp | 14 ++++----
> > src/libcamera/stream.cpp | 2 --
> > src/libcamera/timer.cpp | 2 +-
> > src/libcamera/v4l2_device.cpp | 9 ++---
> > src/libcamera/v4l2_subdevice.cpp | 5 ---
> > 18 files changed, 116 insertions(+), 98 deletions(-)
> >
> > diff --git a/Documentation/coding-style.rst b/Documentation/coding-style.rst
> > index 065fbe0ab07b..8dd1afce1a2c 100644
> > --- a/Documentation/coding-style.rst
> > +++ b/Documentation/coding-style.rst
> > @@ -171,6 +171,55 @@ These rules match the `object ownership rules from the Chromium C++ Style Guide`
> > documented explicitly in details in the API.
> >
> >
> > +Documentation
> > +-------------
> > +
> > +All public and protected classes, structures, enumerations, macros, functions
> > +and variables shall be documented with a Doxygen comment block, using the
> > +Javadoc style with C-style comments. When documenting private member functions
> > +and variables the same Doxygen style shall be used as for public and protected
> > +members.
> > +
> > +Documentation relates to header files, but shall be stored in the .cpp source
> > +files in order to group the implementation and documentation. Every documented
> > +header file shall have a \file documentation block in the .cpp source file.
> > +
> > +The following comment block shows an example of correct documentation for a
> > +member function of the PipelineHandler class.
> > +
> > +::
> > +
> > + /**
> > + * \fn PipelineHandler::start()
> > + * \brief Start capturing from a group of streams
> > + * \param[in] camera The camera to start
> > + *
> > + * Start the group of streams that have been configured for capture by
> > + * \a configureStreams(). The intended caller of this method is the Camera
> > + * class which will in turn be called from the application to indicate that
> > + * it has configured the streams and is ready to capture.
> > + *
> > + * \return 0 on success or a negative error code otherwise
> > + */
> > +
> > +The comment block shall be placed right before the function it documents. If
> > +the function is defined inline in the class definition in the header file, the
> > +comment block shall be placed alone in the .cpp source file in the same order
> > +as the function definitions in the header file and shall start with an \fn
> > +line. Otherwise no \fn line shall be present.
> > +
> > +The \brief directive shall be present. If the function takes parameters, \param
> > +directives shall be present, with the appropriate [in], [out] or [inout]
> > +specifiers. Only when the direction of the parameters isn't known (for instance
> > +when defining a template function with variadic arguments) the direction
> > +specifier shall be omitted. The \return directive shall be present when the
> > +function returns a value, and shall be omitted otherwise.
> > +
> > +The long description is optional. When present it shall be surrounded by empty
> > +lines and may span multiple paragraphs. No blank lines shall otherwise be added
> > +between the \fn, \brief, \param and \return directives.
> > +
>
> Additional blank line... was it intentional?
Yes, we have two blank lines between major sections.
> > +
> > Tools
> > -----
> >
> > diff --git a/src/libcamera/camera.cpp b/src/libcamera/camera.cpp
> > index bd381fa1cb56..69406b515700 100644
> > --- a/src/libcamera/camera.cpp
> > +++ b/src/libcamera/camera.cpp
> > @@ -77,7 +77,6 @@ CameraConfiguration::CameraConfiguration()
> >
> > /**
> > * \brief Retrieve an iterator to the first stream in the sequence
> > - *
> > * \return An iterator to the first stream
> > */
> > std::vector<Stream *>::iterator CameraConfiguration::begin()
> > @@ -88,7 +87,6 @@ std::vector<Stream *>::iterator CameraConfiguration::begin()
> > /**
> > * \brief Retrieve an iterator pointing to the past-the-end stream in the
> > * sequence
> > - *
> > * \return An iterator to the element following the last stream
> > */
> > std::vector<Stream *>::iterator CameraConfiguration::end()
> > @@ -98,7 +96,6 @@ std::vector<Stream *>::iterator CameraConfiguration::end()
> >
> > /**
> > * \brief Retrieve a const iterator to the first element of the streams
> > - *
> > * \return A const iterator to the first stream
> > */
> > std::vector<Stream *>::const_iterator CameraConfiguration::begin() const
> > @@ -109,7 +106,6 @@ std::vector<Stream *>::const_iterator CameraConfiguration::begin() const
> > /**
> > * \brief Retrieve a const iterator pointing to the past-the-end stream in the
> > * sequence
> > - *
> > * \return A const iterator to the element following the last stream
> > */
> > std::vector<Stream *>::const_iterator CameraConfiguration::end() const
> > @@ -144,7 +140,6 @@ bool CameraConfiguration::isValid() const
> >
> > /**
> > * \brief Check if the camera configuration is empty
> > - *
> > * \return True if the configuration is empty
> > */
> > bool CameraConfiguration::isEmpty() const
> > @@ -154,7 +149,6 @@ bool CameraConfiguration::isEmpty() const
> >
> > /**
> > * \brief Retrieve the number of stream configurations
> > - *
> > * \return Number of stream configurations
> > */
> > std::size_t CameraConfiguration::size() const
> > @@ -164,7 +158,6 @@ std::size_t CameraConfiguration::size() const
> >
> > /**
> > * \brief Access the first stream in the configuration
> > - *
> > * \return The first stream in the configuration
> > */
> > Stream *CameraConfiguration::front()
> > @@ -174,7 +167,6 @@ Stream *CameraConfiguration::front()
> >
> > /**
> > * \brief Access the first stream in the configuration
> > - *
> > * \return The first const stream pointer in the configuration
> > */
> > const Stream *CameraConfiguration::front() const
> > @@ -359,7 +351,6 @@ std::shared_ptr<Camera> Camera::create(PipelineHandler *pipe,
> >
> > /**
> > * \brief Retrieve the name of the camera
> > - *
> > * \return Name of the camera device
> > */
> > const std::string &Camera::name() const
> > diff --git a/src/libcamera/camera_manager.cpp b/src/libcamera/camera_manager.cpp
> > index 66a42b357c87..e2473816b252 100644
> > --- a/src/libcamera/camera_manager.cpp
> > +++ b/src/libcamera/camera_manager.cpp
> > @@ -151,7 +151,6 @@ void CameraManager::stop()
> >
> > /**
> > * \brief Get a camera based on name
> > - *
> > * \param[in] name Name of camera to get
> > *
> > * Before calling this function the caller is responsible for ensuring that
> > @@ -229,7 +228,7 @@ CameraManager *CameraManager::instance()
> >
> > /**
> > * \brief Set the event dispatcher
> > - * \param dispatcher Pointer to the event dispatcher
> > + * \param[in] dispatcher Pointer to the event dispatcher
> > *
> > * libcamera requires an event dispatcher to integrate event notification and
> > * timers with the application event loop. Applications that want to provide
> > diff --git a/src/libcamera/camera_sensor.cpp b/src/libcamera/camera_sensor.cpp
> > index ca4dd0c92efa..52bd8f6fb973 100644
> > --- a/src/libcamera/camera_sensor.cpp
> > +++ b/src/libcamera/camera_sensor.cpp
> > @@ -242,7 +242,6 @@ V4L2SubdeviceFormat CameraSensor::getFormat(const std::vector<unsigned int> &mbu
> > /**
> > * \brief Set the sensor output format
> > * \param[in] format The desired sensor output format
> > - *
> > * \return 0 on success or a negative error code otherwise
> > */
> > int CameraSensor::setFormat(V4L2SubdeviceFormat *format)
> > diff --git a/src/libcamera/device_enumerator.cpp b/src/libcamera/device_enumerator.cpp
> > index 58b81c354a70..e7de415b7139 100644
> > --- a/src/libcamera/device_enumerator.cpp
> > +++ b/src/libcamera/device_enumerator.cpp
> > @@ -317,8 +317,8 @@ std::shared_ptr<MediaDevice> DeviceEnumerator::search(const DeviceMatch &dm)
> > /**
> > * \fn DeviceEnumerator::lookupDeviceNode(int major, int minor)
> > * \brief Lookup device node path from device number
> > - * \param major The device major number
> > - * \param minor The device minor number
> > + * \param[in] major The device major number
> > + * \param[in] minor The device minor number
> > *
> > * Translate a device number given as \a major and \a minor to a device node
> > * path.
> > diff --git a/src/libcamera/event_dispatcher.cpp b/src/libcamera/event_dispatcher.cpp
> > index b82c59c3f5dc..bb4fddfffe86 100644
> > --- a/src/libcamera/event_dispatcher.cpp
> > +++ b/src/libcamera/event_dispatcher.cpp
> > @@ -42,7 +42,7 @@ EventDispatcher::~EventDispatcher()
> > /**
> > * \fn EventDispatcher::registerEventNotifier()
> > * \brief Register an event notifier
> > - * \param notifier The event notifier to register
> > + * \param[in] notifier The event notifier to register
> > *
> > * Once the \a notifier is registered with the dispatcher, the dispatcher will
> > * emit the notifier \ref EventNotifier::activated signal whenever a
> > @@ -57,7 +57,7 @@ EventDispatcher::~EventDispatcher()
> > /**
> > * \fn EventDispatcher::unregisterEventNotifier()
> > * \brief Unregister an event notifier
> > - * \param notifier The event notifier to unregister
> > + * \param[in] notifier The event notifier to unregister
> > *
> > * After this function returns the \a notifier is guaranteed not to emit the
> > * \ref EventNotifier::activated signal.
> > @@ -68,7 +68,7 @@ EventDispatcher::~EventDispatcher()
> > /**
> > * \fn EventDispatcher::registerTimer()
> > * \brief Register a timer
> > - * \param timer The timer to register
> > + * \param[in] timer The timer to register
> > *
> > * Once the \a timer is registered with the dispatcher, the dispatcher will emit
> > * the timer \ref Timer::timeout signal when the timer times out. The timer can
> > @@ -86,7 +86,7 @@ EventDispatcher::~EventDispatcher()
> > /**
> > * \fn EventDispatcher::unregisterTimer()
> > * \brief Unregister a timer
> > - * \param timer The timer to unregister
> > + * \param[in] timer The timer to unregister
> > *
> > * After this function returns the \a timer is guaranteed not to emit the
> > * \ref Timer::timeout signal.
> > diff --git a/src/libcamera/event_notifier.cpp b/src/libcamera/event_notifier.cpp
> > index 71775a9cb41f..0f84e4128169 100644
> > --- a/src/libcamera/event_notifier.cpp
> > +++ b/src/libcamera/event_notifier.cpp
> > @@ -55,8 +55,8 @@ namespace libcamera {
> >
> > /**
> > * \brief Construct an event notifier with a file descriptor and event type
> > - * \param fd The file descriptor to monitor
> > - * \param type The event type to monitor
> > + * \param[in] fd The file descriptor to monitor
> > + * \param[in] type The event type to monitor
> > */
> > EventNotifier::EventNotifier(int fd, Type type)
> > : fd_(fd), type_(type), enabled_(false)
> > @@ -90,7 +90,7 @@ EventNotifier::~EventNotifier()
> >
> > /**
> > * \brief Enable or disable the notifier
> > - * \param enable True to enable the notifier, false to disable it
> > + * \param[in] enable True to enable the notifier, false to disable it
> > *
> > * This function enables or disables the notifier. A disabled notifier ignores
> > * events and does not emit the \ref activated signal.
> > diff --git a/src/libcamera/geometry.cpp b/src/libcamera/geometry.cpp
> > index d14c925aaad2..a39b85e4e904 100644
> > --- a/src/libcamera/geometry.cpp
> > +++ b/src/libcamera/geometry.cpp
> > @@ -51,7 +51,6 @@ namespace libcamera {
> >
> > /**
> > * \brief Assemble and return a string describing the rectangle
> > - *
> > * \return A string describing the Rectangle
> > */
> > const std::string Rectangle::toString() const
> > @@ -94,8 +93,8 @@ bool operator==(const Rectangle &lhs, const Rectangle &rhs)
> > /**
> > * \fn Size::Size(unsigned int width, unsigned int height)
> > * \brief Construct a Size with given \a width and \a height
> > - * \param width The Size width
> > - * \param height The Size height
> > + * \param[in] width The Size width
> > + * \param[in] height The Size height
> > */
> >
> > /**
> > @@ -191,10 +190,10 @@ bool operator<(const Size &lhs, const Size &rhs)
> > /**
> > * \fn SizeRange::SizeRange(unsigned int minW, unsigned int minH, unsigned int maxW, unsigned int maxH)
> > * \brief Construct an initialized size range
> > - * \param minW The minimum width
> > - * \param minH The minimum height
> > - * \param maxW The maximum width
> > - * \param maxH The maximum height
> > + * \param[in] minW The minimum width
> > + * \param[in] minH The minimum height
> > + * \param[in] maxW The maximum width
> > + * \param[in] maxH The maximum height
> > */
> >
> > /**
> > diff --git a/src/libcamera/media_device.cpp b/src/libcamera/media_device.cpp
> > index 1e9024bf9721..9c438ce8b41f 100644
> > --- a/src/libcamera/media_device.cpp
> > +++ b/src/libcamera/media_device.cpp
> > @@ -63,7 +63,7 @@ LOG_DEFINE_CATEGORY(MediaDevice)
> >
> > /**
> > * \brief Construct a MediaDevice
> > - * \param deviceNode The media device node path
> > + * \param[in] deviceNode The media device node path
> > *
> > * Once constructed the media device is invalid, and must be opened and
> > * populated with open() and populate() before the media graph can be queried.
> > @@ -306,9 +306,8 @@ int MediaDevice::populate()
> >
> > /**
> > * \brief Return the MediaEntity with name \a name
> > - * \param name The entity name
> > - * \return The entity with \a name
> > - * \return nullptr if no entity with \a name is found
> > + * \param[in] name The entity name
> > + * \return The entity with \a name, or nullptr if no such entity is found
> > */
> > MediaEntity *MediaDevice::getEntityByName(const std::string &name) const
> > {
> > @@ -322,10 +321,10 @@ MediaEntity *MediaDevice::getEntityByName(const std::string &name) const
> > /**
> > * \brief Retrieve the MediaLink connecting two pads, identified by entity
> > * names and pad indexes
> > - * \param sourceName The source entity name
> > - * \param sourceIdx The index of the source pad
> > - * \param sinkName The sink entity name
> > - * \param sinkIdx The index of the sink pad
> > + * \param[in] sourceName The source entity name
> > + * \param[in] sourceIdx The index of the source pad
> > + * \param[in] sinkName The sink entity name
> > + * \param[in] sinkIdx The index of the sink pad
> > *
> > * Find the link that connects the pads at index \a sourceIdx of the source
> > * entity with name \a sourceName, to the pad at index \a sinkIdx of the
> > @@ -351,10 +350,10 @@ MediaLink *MediaDevice::link(const std::string &sourceName, unsigned int sourceI
> > /**
> > * \brief Retrieve the MediaLink connecting two pads, identified by the
> > * entities they belong to and pad indexes
> > - * \param source The source entity
> > - * \param sourceIdx The index of the source pad
> > - * \param sink The sink entity
> > - * \param sinkIdx The index of the sink pad
> > + * \param[in] source The source entity
> > + * \param[in] sourceIdx The index of the source pad
> > + * \param[in] sink The sink entity
> > + * \param[in] sinkIdx The index of the sink pad
> > *
> > * Find the link that connects the pads at index \a sourceIdx of the source
> > * entity \a source, to the pad at index \a sinkIdx of the sink entity \a
> > @@ -380,8 +379,8 @@ MediaLink *MediaDevice::link(const MediaEntity *source, unsigned int sourceIdx,
> >
> > /**
> > * \brief Retrieve the MediaLink that connects two pads
> > - * \param source The source pad
> > - * \param sink The sink pad
> > + * \param[in] source The source pad
> > + * \param[in] sink The sink pad
> > *
> > * \sa MediaDevice::link(const std::string &sourceName, unsigned int sourceIdx, const std::string &sinkName, unsigned int sinkIdx) const
> > * \sa MediaDevice::link(const MediaEntity *source, unsigned int sourceIdx, const MediaEntity *sink, unsigned int sinkIdx) const
> > @@ -507,8 +506,8 @@ void MediaDevice::clear()
> >
> > /**
> > * \brief Find the interface associated with an entity
> > - * \param topology The media topology as returned by MEDIA_IOC_G_TOPOLOGY
> > - * \param entityId The entity id
> > + * \param[in] topology The media topology as returned by MEDIA_IOC_G_TOPOLOGY
> > + * \param[in] entityId The entity id
> > * \return A pointer to the interface if found, or nullptr otherwise
> > */
> > struct media_v2_interface *MediaDevice::findInterface(const struct media_v2_topology &topology,
> > @@ -694,8 +693,8 @@ void MediaDevice::fixupEntityFlags(struct media_v2_entity *entity)
> >
> > /**
> > * \brief Apply \a flags to a link between two pads
> > - * \param link The link to apply flags to
> > - * \param flags The flags to apply to the link
> > + * \param[in] link The link to apply flags to
> > + * \param[in] flags The flags to apply to the link
> > *
> > * This function applies the link \a flags (as defined by the MEDIA_LNK_FL_*
> > * macros from the Media Controller API) to the given \a link. It implements
> > diff --git a/src/libcamera/media_object.cpp b/src/libcamera/media_object.cpp
> > index f95d7d8e0e4b..bbb8fb64465f 100644
> > --- a/src/libcamera/media_object.cpp
> > +++ b/src/libcamera/media_object.cpp
> > @@ -58,8 +58,8 @@ LOG_DECLARE_CATEGORY(MediaDevice)
> > * \fn MediaObject::MediaObject()
> > * \brief Construct a MediaObject part of the MediaDevice \a dev,
> > * identified by the \a id unique within the device
> > - * \param dev The media device this object belongs to
> > - * \param id The media object id
> > + * \param[in] dev The media device this object belongs to
> > + * \param[in] id The media object id
> > *
> > * The caller shall ensure unicity of the object id in the media device context.
> > * This constraint is neither enforced nor checked by the MediaObject.
> > @@ -100,7 +100,7 @@ LOG_DECLARE_CATEGORY(MediaDevice)
> >
> > /**
> > * \brief Enable or disable a link
> > - * \param enable True to enable the link, false to disable it
> > + * \param[in] enable True to enable the link, false to disable it
> > *
> > * Set the status of a link according to the value of \a enable.
> > * Links between two pads can be set to the enabled or disabled state freely,
> > @@ -128,9 +128,9 @@ int MediaLink::setEnabled(bool enable)
> >
> > /**
> > * \brief Construct a MediaLink
> > - * \param link The media link kernel data
> > - * \param source The source pad at the origin of the link
> > - * \param sink The sink pad at the destination of the link
> > + * \param[in] link The media link kernel data
> > + * \param[in] source The source pad at the origin of the link
> > + * \param[in] sink The sink pad at the destination of the link
> > */
> > MediaLink::MediaLink(const struct media_v2_link *link, MediaPad *source,
> > MediaPad *sink)
> > @@ -181,8 +181,8 @@ MediaLink::MediaLink(const struct media_v2_link *link, MediaPad *source,
> >
> > /**
> > * \brief Construct a MediaPad
> > - * \param pad The media pad kernel data
> > - * \param entity The entity the pad belongs to
> > + * \param[in] pad The media pad kernel data
> > + * \param[in] entity The entity the pad belongs to
> > */
> > MediaPad::MediaPad(const struct media_v2_pad *pad, MediaEntity *entity)
> > : MediaObject(entity->device(), pad->id), index_(pad->index), entity_(entity),
> > @@ -230,7 +230,7 @@ MediaPad::~MediaPad()
> >
> > /**
> > * \brief Add a new link to this pad
> > - * \param link The MediaLink to add
> > + * \param[in] link The MediaLink to add
> > */
> > void MediaPad::addLink(MediaLink *link)
> > {
> > @@ -278,10 +278,8 @@ void MediaPad::addLink(MediaLink *link)
> > /**
> > * \fn MediaEntity::deviceNode()
> > * \brief Retrieve the entity's device node path, if any
> > - *
> > - * \sa int setDeviceNode()
> > - *
> > * \return The entity's device node path, or an empty string if it is not set
> > + * \sa int setDeviceNode()
> > */
> >
> > /**
> > @@ -306,7 +304,7 @@ void MediaPad::addLink(MediaLink *link)
> >
> > /**
> > * \brief Get a pad in this entity by its index
> > - * \param index The 0-based pad index
> > + * \param[in] index The 0-based pad index
> > * \return The pad identified by \a index, or nullptr if no such pad exist
> > */
> > const MediaPad *MediaEntity::getPadByIndex(unsigned int index) const
> > @@ -321,7 +319,7 @@ const MediaPad *MediaEntity::getPadByIndex(unsigned int index) const
> >
> > /**
> > * \brief Get a pad in this entity by its object id
> > - * \param id The pad id
> > + * \param[in] id The pad id
> > * \return The pad identified by \a id, or nullptr if no such pad exist
> > */
> > const MediaPad *MediaEntity::getPadById(unsigned int id) const
> > @@ -336,7 +334,7 @@ const MediaPad *MediaEntity::getPadById(unsigned int id) const
> >
> > /**
> > * \brief Set the path to the device node for the associated interface
> > - * \param deviceNode The interface device node path associated with this entity
> > + * \param[in] deviceNode The interface device node path associated with this entity
> > * \return 0 on success or a negative error code otherwise
> > */
> > int MediaEntity::setDeviceNode(const std::string &deviceNode)
> > @@ -358,10 +356,10 @@ int MediaEntity::setDeviceNode(const std::string &deviceNode)
> >
> > /**
> > * \brief Construct a MediaEntity
> > - * \param dev The media device this entity belongs to
> > - * \param entity The media entity kernel data
> > - * \param major The major number of the entity associated interface
> > - * \param minor The minor number of the entity associated interface
> > + * \param[in] dev The media device this entity belongs to
> > + * \param[in] entity The media entity kernel data
> > + * \param[in] major The major number of the entity associated interface
> > + * \param[in] minor The minor number of the entity associated interface
> > */
> > MediaEntity::MediaEntity(MediaDevice *dev,
> > const struct media_v2_entity *entity,
> > @@ -383,7 +381,7 @@ MediaEntity::~MediaEntity()
> >
> > /**
> > * \brief Add \a pad to the entity's list of pads
> > - * \param pad The pad to add to the list
> > + * \param[in] pad The pad to add to the list
> > *
> > * This function is meant to add pads to the entity during parsing of the media
> > * graph, after the MediaPad objects are constructed and before the MediaDevice
> > diff --git a/src/libcamera/pipeline/ipu3/ipu3.cpp b/src/libcamera/pipeline/ipu3/ipu3.cpp
> > index 64b4210b4ce3..405d6548fd01 100644
> > --- a/src/libcamera/pipeline/ipu3/ipu3.cpp
> > +++ b/src/libcamera/pipeline/ipu3/ipu3.cpp
> > @@ -613,7 +613,7 @@ int PipelineHandlerIPU3::registerCameras()
> >
> > /**
> > * \brief Handle buffers completion at the ImgU input
> > - * \param buffer The completed buffer
> > + * \param[in] buffer The completed buffer
> > *
> > * Buffers completed from the ImgU input are immediately queued back to the
> > * CIO2 unit to continue frame capture.
> > @@ -625,7 +625,7 @@ void PipelineHandlerIPU3::IPU3CameraData::imguInputBufferReady(Buffer *buffer)
> >
> > /**
> > * \brief Handle buffers completion at the ImgU output
> > - * \param buffer The completed buffer
> > + * \param[in] buffer The completed buffer
> > *
> > * Buffers completed from the ImgU output are directed to the application.
> > */
> > @@ -639,7 +639,7 @@ void PipelineHandlerIPU3::IPU3CameraData::imguOutputBufferReady(Buffer *buffer)
> >
> > /**
> > * \brief Handle buffers completion at the CIO2 output
> > - * \param buffer The completed buffer
> > + * \param[in] buffer The completed buffer
> > *
> > * Buffers completed from the CIO2 are immediately queued to the ImgU unit
> > * for further processing.
> > @@ -723,7 +723,6 @@ int ImgUDevice::init(MediaDevice *media, unsigned int index)
> > * \brief Configure the ImgU unit input
> > * \param[in] config The requested stream configuration
> > * \param[in] inputFormat The format to be applied to ImgU input
> > - *
> > * \return 0 on success or a negative error code otherwise
> > */
> > int ImgUDevice::configureInput(const StreamConfiguration &config,
> > @@ -781,7 +780,6 @@ int ImgUDevice::configureInput(const StreamConfiguration &config,
> > * \brief Configure the ImgU unit \a id video output
> > * \param[in] output The ImgU output device to configure
> > * \param[in] config The requested configuration
> > - *
> > * \return 0 on success or a negative error code otherwise
> > */
> > int ImgUDevice::configureOutput(ImgUOutput *output,
> > @@ -822,7 +820,6 @@ int ImgUDevice::configureOutput(ImgUOutput *output,
> > /**
> > * \brief Import buffers from \a pool into the ImgU input
> > * \param[in] pool The buffer pool to import
> > - *
> > * \return 0 on success or a negative error code otherwise
> > */
> > int ImgUDevice::importBuffers(BufferPool *pool)
> > @@ -1082,7 +1079,6 @@ int CIO2Device::init(const MediaDevice *media, unsigned int index)
> > * \brief Configure the CIO2 unit
> > * \param[in] config The requested configuration
> > * \param[out] outputFormat The CIO2 unit output image format
> > - *
> > * \return 0 on success or a negative error code otherwise
> > */
> > int CIO2Device::configure(const StreamConfiguration &config,
> > diff --git a/src/libcamera/pipeline_handler.cpp b/src/libcamera/pipeline_handler.cpp
> > index 911d08448e69..f7a8a1ac3be6 100644
> > --- a/src/libcamera/pipeline_handler.cpp
> > +++ b/src/libcamera/pipeline_handler.cpp
> > @@ -120,7 +120,7 @@ PipelineHandler::~PipelineHandler()
> > /**
> > * \fn PipelineHandler::match(DeviceEnumerator *enumerator)
> > * \brief Match media devices and create camera instances
> > - * \param enumerator The enumerator providing all media devices found in the
> > + * \param[in] enumerator The enumerator providing all media devices found in the
> > * system
> > *
> > * This function is the main entry point of the pipeline handler. It is called
> > @@ -413,8 +413,7 @@ void PipelineHandler::disconnect()
> >
> > /**
> > * \brief Retrieve the pipeline-specific data associated with a Camera
> > - * \param camera The camera whose data to retrieve
> > - *
> > + * \param[in] camera The camera whose data to retrieve
> > * \return A pointer to the pipeline-specific data passed to registerCamera().
> > * The returned pointer is a borrowed reference and is guaranteed to remain
> > * valid until the pipeline handler is destroyed. It shall not be deleted
> > diff --git a/src/libcamera/request.cpp b/src/libcamera/request.cpp
> > index 433c6f83a25b..ef65c42f9da7 100644
> > --- a/src/libcamera/request.cpp
> > +++ b/src/libcamera/request.cpp
> > @@ -90,7 +90,6 @@ int Request::setBuffers(const std::map<Stream *, Buffer *> &streamMap)
> > /**
> > * \brief Return the buffer associated with a stream
> > * \param[in] stream The stream the buffer is associated to
> > - *
> > * \return The buffer associated with the stream, or nullptr if the stream is
> > * not part of this request
> > */
> > diff --git a/src/libcamera/signal.cpp b/src/libcamera/signal.cpp
> > index cb7daa11dab1..f97d68b3e8bf 100644
> > --- a/src/libcamera/signal.cpp
> > +++ b/src/libcamera/signal.cpp
> > @@ -45,8 +45,8 @@ namespace libcamera {
> > /**
> > * \fn Signal::connect(T *object, void(T::*func)(Args...))
> > * \brief Connect the signal to a member function slot
> > - * \param object The slot object pointer
> > - * \param func The slot member function
> > + * \param[in] object The slot object pointer
> > + * \param[in] func The slot member function
> > *
> > * If the typename T inherits from Object, the signal will be automatically
> > * disconnected from the \a func slot of \a object when \a object is destroyed.
> > @@ -57,7 +57,7 @@ namespace libcamera {
> > /**
> > * \fn Signal::connect(void(*func)(Args...))
> > * \brief Connect the signal to a static function slot
> > - * \param func The slot static function
> > + * \param[in] func The slot static function
> > */
> >
> > /**
> > @@ -68,20 +68,20 @@ namespace libcamera {
> > /**
> > * \fn Signal::disconnect(T *object)
> > * \brief Disconnect the signal from all slots of the \a object
> > - * \param object The object pointer whose slots to disconnect
> > + * \param[in] object The object pointer whose slots to disconnect
> > */
> >
> > /**
> > * \fn Signal::disconnect(T *object, void(T::*func)(Args...))
> > * \brief Disconnect the signal from the \a object slot member function \a func
> > - * \param object The object pointer whose slots to disconnect
> > - * \param func The slot member function to disconnect
> > + * \param[in] object The object pointer whose slots to disconnect
> > + * \param[in] func The slot member function to disconnect
> > */
> >
> > /**
> > * \fn Signal::disconnect(void(*func)(Args...))
> > * \brief Disconnect the signal from the slot static function \a func
> > - * \param func The slot static function to disconnect
> > + * \param[in] func The slot static function to disconnect
> > */
> >
> > /**
> > diff --git a/src/libcamera/stream.cpp b/src/libcamera/stream.cpp
> > index 85cd5256ee2f..d4ef506cea95 100644
> > --- a/src/libcamera/stream.cpp
> > +++ b/src/libcamera/stream.cpp
> > @@ -88,14 +88,12 @@ namespace libcamera {
> > /**
> > * \fn StreamUsage::role()
> > * \brief Retrieve the stream role
> > - *
> > * \return The stream role
> > */
> >
> > /**
> > * \fn StreamUsage::size()
> > * \brief Retrieve desired size
> > - *
> > * \return The desired size
> > */
> >
> > diff --git a/src/libcamera/timer.cpp b/src/libcamera/timer.cpp
> > index e964a94bc48d..f42e479b996e 100644
> > --- a/src/libcamera/timer.cpp
> > +++ b/src/libcamera/timer.cpp
> > @@ -44,7 +44,7 @@ Timer::Timer()
> >
> > /**
> > * \brief Start or restart the timer with a timeout of \a msec
> > - * \param msec The timer duration in milliseconds
> > + * \param[in] msec The timer duration in milliseconds
> > *
> > * If the timer is already running it will be stopped and restarted.
> > */
> > diff --git a/src/libcamera/v4l2_device.cpp b/src/libcamera/v4l2_device.cpp
> > index d394632dad4c..ccc5fbfc2268 100644
> > --- a/src/libcamera/v4l2_device.cpp
> > +++ b/src/libcamera/v4l2_device.cpp
> > @@ -228,7 +228,6 @@ LOG_DEFINE_CATEGORY(V4L2)
> >
> > /**
> > * \brief Assemble and return a string describing the format
> > - *
> > * \return A string describing the V4L2DeviceFormat
> > */
> > const std::string V4L2DeviceFormat::toString() const
> > @@ -267,7 +266,7 @@ const std::string V4L2DeviceFormat::toString() const
> >
> > /**
> > * \brief Construct a V4L2Device
> > - * \param deviceNode The file-system path to the video device node
> > + * \param[in] deviceNode The file-system path to the video device node
> > */
> > V4L2Device::V4L2Device(const std::string &deviceNode)
> > : deviceNode_(deviceNode), fd_(-1), bufferPool_(nullptr),
> > @@ -283,7 +282,7 @@ V4L2Device::V4L2Device(const std::string &deviceNode)
> >
> > /**
> > * \brief Construct a V4L2Device from a MediaEntity
> > - * \param entity The MediaEntity to build the device from
> > + * \param[in] entity The MediaEntity to build the device from
> > *
> > * Construct a V4L2Device from a MediaEntity's device node path.
> > */
> > @@ -421,7 +420,6 @@ std::string V4L2Device::logPrefix() const
> > /**
> > * \brief Retrieve the image format set on the V4L2 device
> > * \param[out] format The image format applied on the device
> > - *
> > * \return 0 on success or a negative error code otherwise
> > */
> > int V4L2Device::getFormat(V4L2DeviceFormat *format)
> > @@ -432,7 +430,7 @@ int V4L2Device::getFormat(V4L2DeviceFormat *format)
> >
> > /**
> > * \brief Configure an image format on the V4L2 device
> > - * \param[in] format The image format to apply to the device
> > + * \param[inout] format The image format to apply to the device
> > *
> > * Apply the supplied \a format to the device, and return the actually
> > * applied format parameters, as \ref V4L2Device::getFormat would do.
> > @@ -885,7 +883,6 @@ void V4L2Device::bufferAvailable(EventNotifier *notifier)
> >
> > /**
> > * \brief Start the video stream
> > - *
> > * \return 0 on success or a negative error code otherwise
> > */
> > int V4L2Device::streamOn()
> > diff --git a/src/libcamera/v4l2_subdevice.cpp b/src/libcamera/v4l2_subdevice.cpp
> > index 5d5b168f98a2..eaa673e994b9 100644
> > --- a/src/libcamera/v4l2_subdevice.cpp
> > +++ b/src/libcamera/v4l2_subdevice.cpp
> > @@ -75,7 +75,6 @@ LOG_DEFINE_CATEGORY(V4L2Subdev)
> >
> > /**
> > * \brief Assemble and return a string describing the format
> > - *
> > * \return A string describing the V4L2SubdeviceFormat
> > */
> > const std::string V4L2SubdeviceFormat::toString() const
> > @@ -119,7 +118,6 @@ V4L2Subdevice::~V4L2Subdevice()
> >
> > /**
> > * \brief Open a V4L2 subdevice
> > - *
> > * \return 0 on success or a negative error code otherwise
> > */
> > int V4L2Subdevice::open()
> > @@ -175,7 +173,6 @@ void V4L2Subdevice::close()
> > * \brief Set a crop rectangle on one of the V4L2 subdevice pads
> > * \param[in] pad The 0-indexed pad number the rectangle is to be applied to
> > * \param[inout] rect The rectangle describing crop target area
> > - *
> > * \return 0 on success or a negative error code otherwise
> > */
> > int V4L2Subdevice::setCrop(unsigned int pad, Rectangle *rect)
> > @@ -187,7 +184,6 @@ int V4L2Subdevice::setCrop(unsigned int pad, Rectangle *rect)
> > * \brief Set a compose rectangle on one of the V4L2 subdevice pads
> > * \param[in] pad The 0-indexed pad number the rectangle is to be applied to
> > * \param[inout] rect The rectangle describing the compose target area
> > - *
> > * \return 0 on success or a negative error code otherwise
> > */
> > int V4L2Subdevice::setCompose(unsigned int pad, Rectangle *rect)
> > @@ -251,7 +247,6 @@ FormatEnum V4L2Subdevice::formats(unsigned int pad)
> > * \brief Retrieve the image format set on one of the V4L2 subdevice pads
> > * \param[in] pad The 0-indexed pad number the format is to be retrieved from
> > * \param[out] format The image bus format
> > - *
> > * \return 0 on success or a negative error code otherwise
> > */
> > int V4L2Subdevice::getFormat(unsigned int pad, V4L2SubdeviceFormat *format)
>
> Thank you for your effort in doing this!
> Acked-by: Jacopo Mondi <jacopo at jmondi.org>
--
Regards,
Laurent Pinchart
More information about the libcamera-devel
mailing list