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