libcamera: Document documentation style and update the code accordingly

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@ideasonboard.com>
Acked-by: Jacopo Mondi <jacopo@jmondi.org>

18 files changed, 116 insertions, 98 deletions

diff --git a/Documentation/coding-style.rst b/Documentation/coding-style.rst
index 065fbe0a..8dd1afce 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.
+
+
 Tools
 -----
 
diff --git a/src/libcamera/camera.cpp b/src/libcamera/camera.cpp
index bd381fa1..69406b51 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 66a42b35..e2473816 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 ca4dd0c9..52bd8f6f 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 58b81c35..e7de415b 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 b82c59c3..bb4fddff 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 71775a9c..0f84e412 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 d14c925a..a39b85e4 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 1e9024bf..9c438ce8 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 f95d7d8e..bbb8fb64 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 64b4210b..405d6548 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 911d0844..f7a8a1ac 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 433c6f83..ef65c42f 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 cb7daa11..f97d68b3 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 85cd5256..d4ef506c 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 e964a94b..f42e479b 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 d394632d..ccc5fbfc 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 5d5b168f..eaa673e9 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)