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