[libcamera-devel] [PATCH 2/8] libcamera: align the documentation for numeric error codes
Niklas Söderlund
niklas.soderlund at ragnatech.se
Tue Feb 26 03:18:51 CET 2019
Rapid growth of the library have resulted in slightly different wording
to document that a function returns 0 on success or a negative error
code. Align all different variations.
Signed-off-by: Niklas Söderlund <niklas.soderlund at ragnatech.se>
---
src/libcamera/buffer.cpp | 6 +++---
src/libcamera/camera.cpp | 12 ++++++------
src/libcamera/camera_manager.cpp | 2 +-
src/libcamera/device_enumerator.cpp | 7 +++----
src/libcamera/media_device.cpp | 8 ++++----
src/libcamera/media_object.cpp | 5 ++---
src/libcamera/pipeline_handler.cpp | 10 +++++-----
src/libcamera/request.cpp | 2 +-
src/libcamera/v4l2_device.cpp | 16 ++++++++--------
src/libcamera/v4l2_subdevice.cpp | 10 +++++-----
10 files changed, 38 insertions(+), 40 deletions(-)
diff --git a/src/libcamera/buffer.cpp b/src/libcamera/buffer.cpp
index 9ec372c2981b5b02..f7c5f0e6a3fe0e55 100644
--- a/src/libcamera/buffer.cpp
+++ b/src/libcamera/buffer.cpp
@@ -71,7 +71,7 @@ Plane::~Plane()
* The \a fd dmabuf file handle is duplicated and stored. The caller may close
* the original file handle.
*
- * \return 0 on success or a negative error value otherwise.
+ * \return 0 on success or a negative error code
*/
int Plane::setDmabuf(int fd, unsigned int length)
{
@@ -106,7 +106,7 @@ int Plane::setDmabuf(int fd, unsigned int length)
*
* \sa setDmaBuf()
*
- * \return 0 on success or a negative error value otherwise.
+ * \return 0 on success or a negative error code
*/
int Plane::mmap()
{
@@ -133,7 +133,7 @@ int Plane::mmap()
*
* Unmap the memory mapped by an earlier call to mmap().
*
- * \return 0 on success or a negative error value otherwise.
+ * \return 0 on success or a negative error code
*/
int Plane::munmap()
{
diff --git a/src/libcamera/camera.cpp b/src/libcamera/camera.cpp
index 6409d10ff88b2189..e2372fea31e2921a 100644
--- a/src/libcamera/camera.cpp
+++ b/src/libcamera/camera.cpp
@@ -157,7 +157,7 @@ void Camera::disconnect()
*
* \todo Implement exclusive access across processes.
*
- * \return 0 on success or a negative error code on error.
+ * \return 0 on success or a negative error code
*/
int Camera::acquire()
{
@@ -235,7 +235,7 @@ Camera::streamConfiguration(std::vector<Stream *> &streams)
* Exclusive access to the camera shall be ensured by a call to acquire() prior
* to calling this function, otherwise an -EACCES error will be returned.
*
- * \return 0 on success or a negative error code on error.
+ * \return 0 on success or a negative error code
* \retval -ENODEV The camera is not connected to any hardware
* \retval -EACCES The user has not acquired exclusive access to the camera
* \retval -EINVAL The configuration is not valid
@@ -278,7 +278,7 @@ int Camera::configureStreams(std::map<Stream *, StreamConfiguration> &config)
/**
* \brief Allocate buffers for all configured streams
- * \return 0 on success or a negative error code otherwise
+ * \return 0 on success or a negative error code
*/
int Camera::allocateBuffers()
{
@@ -350,7 +350,7 @@ Request *Camera::createRequest()
* Ownership of the request is transferred to the camera. It will be deleted
* automatically after it completes.
*
- * \return 0 on success or a negative error code on error
+ * \return 0 on success or a negative error code
*/
int Camera::queueRequest(Request *request)
{
@@ -376,7 +376,7 @@ int Camera::queueRequest(Request *request)
* can queue requests to the camera to process and return to the application
* until the capture session is terminated with \a stop().
*
- * \return 0 on success or a negative error code on error
+ * \return 0 on success or a negative error code
*/
int Camera::start()
{
@@ -395,7 +395,7 @@ int Camera::start()
* This method stops capturing and processing requests immediately. All pending
* requests are cancelled and complete synchronously in an error state.
*
- * \return 0 on success or a negative error code on error
+ * \return 0 on success or a negative error code
*/
int Camera::stop()
{
diff --git a/src/libcamera/camera_manager.cpp b/src/libcamera/camera_manager.cpp
index f90201ade18b61dd..6878cc7e26b24ca4 100644
--- a/src/libcamera/camera_manager.cpp
+++ b/src/libcamera/camera_manager.cpp
@@ -74,7 +74,7 @@ CameraManager::~CameraManager()
* interact with cameras in the system until either the camera manager
* is stopped or the camera is unplugged from the system.
*
- * \return 0 on successful start, or a negative error code otherwise
+ * \return 0 on success or a negative error code
*/
int CameraManager::start()
{
diff --git a/src/libcamera/device_enumerator.cpp b/src/libcamera/device_enumerator.cpp
index 66819f077c16c721..b35ac2bb626ec3c6 100644
--- a/src/libcamera/device_enumerator.cpp
+++ b/src/libcamera/device_enumerator.cpp
@@ -178,7 +178,7 @@ DeviceEnumerator::~DeviceEnumerator()
/**
* \fn DeviceEnumerator::init()
* \brief Initialize the enumerator
- * \return 0 on success, or a negative error code otherwise
+ * \return 0 on success or a negative error code
* \retval -EBUSY the enumerator has already been initialized
* \retval -ENODEV the enumerator can't enumerate devices
*/
@@ -195,7 +195,7 @@ DeviceEnumerator::~DeviceEnumerator()
* with a warning message logged, without returning an error. Only errors that
* prevent enumeration altogether shall be fatal.
*
- * \return 0 on success, or a negative error code on fatal errors.
+ * \return 0 on success or a negative error code
*/
/**
@@ -206,8 +206,7 @@ DeviceEnumerator::~DeviceEnumerator()
* and look up device nodes associated with all entities. Store the media device
* in the internal list for later matching with pipeline handlers.
*
- * \return 0 on success, or a negative error code if the media device can't be
- * created or populated
+ * \return 0 on success or a negative error code
*/
int DeviceEnumerator::addDevice(const std::string &deviceNode)
{
diff --git a/src/libcamera/media_device.cpp b/src/libcamera/media_device.cpp
index 800ed330fe6d8d6f..4f494e316867a55c 100644
--- a/src/libcamera/media_device.cpp
+++ b/src/libcamera/media_device.cpp
@@ -136,7 +136,7 @@ bool MediaDevice::acquire()
*
* If the device is already open the function returns -EBUSY.
*
- * \return 0 on success or a negative error code otherwise
+ * \return 0 on success or a negative error code
*/
int MediaDevice::open()
{
@@ -206,7 +206,7 @@ void MediaDevice::close()
* while pads are accessible from the entity they belong to and links from the
* pads they connect.
*
- * \return 0 on success, a negative error code otherwise
+ * \return 0 on success or a negative error code
*/
int MediaDevice::populate()
{
@@ -405,7 +405,7 @@ MediaLink *MediaDevice::link(const MediaPad *source, const MediaPad *sink)
* Disable all the media device links, clearing the MEDIA_LNK_FL_ENABLED flag
* on links which are not flagged as IMMUTABLE.
*
- * \return 0 on success, or a negative error code otherwise
+ * \return 0 on success or a negative error code
*/
int MediaDevice::disableLinks()
{
@@ -705,7 +705,7 @@ void MediaDevice::fixupEntityFlags(struct media_v2_entity *entity)
*
* \sa MediaLink::setEnabled(bool enable)
*
- * \return 0 on success, or a negative error code otherwise
+ * \return 0 on success or a negative error code
*/
int MediaDevice::setupLink(const MediaLink *link, unsigned int flags)
{
diff --git a/src/libcamera/media_object.cpp b/src/libcamera/media_object.cpp
index f6abcd8676a3866d..79126124caf98497 100644
--- a/src/libcamera/media_object.cpp
+++ b/src/libcamera/media_object.cpp
@@ -111,7 +111,7 @@ LOG_DECLARE_CATEGORY(MediaDevice)
* Enabling a link establishes a data connection between two pads, while
* disabling it interrupts that connection.
*
- * \return 0 on success, or a negative error code otherwise
+ * \return 0 on success or a negative error code
*/
int MediaLink::setEnabled(bool enable)
{
@@ -337,8 +337,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
- * \return 0 on success, or a negative error code if the device node can't be
- * accessed
+ * \return 0 on success or a negative error code
*/
int MediaEntity::setDeviceNode(const std::string &deviceNode)
{
diff --git a/src/libcamera/pipeline_handler.cpp b/src/libcamera/pipeline_handler.cpp
index dad0a2964486c5d4..0a858fbe13257c7f 100644
--- a/src/libcamera/pipeline_handler.cpp
+++ b/src/libcamera/pipeline_handler.cpp
@@ -144,7 +144,7 @@ PipelineHandler::~PipelineHandler()
* configuration of a subset of the streams can't be satisfied, the
* whole configuration is considered invalid.
*
- * \return 0 on success or a negative error code on error.
+ * \return 0 on success or a negative error code
*/
/**
@@ -158,7 +158,7 @@ PipelineHandler::~PipelineHandler()
*
* The intended caller of this method is the Camera class.
*
- * \return 0 on success or a negative error code on error
+ * \return 0 on success or a negative error code
*/
/**
@@ -172,7 +172,7 @@ PipelineHandler::~PipelineHandler()
*
* The intended caller of this method is the Camera class.
*
- * \return 0 on success or a negative error code on error
+ * \return 0 on success or a negative error code
*/
/**
@@ -185,7 +185,7 @@ PipelineHandler::~PipelineHandler()
* 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 on error
+ * \return 0 on success or a negative error code
*/
/**
@@ -211,7 +211,7 @@ PipelineHandler::~PipelineHandler()
* parameters will be applied to the frames captured in the buffers provided in
* the request.
*
- * \return 0 on success or a negative error code on error
+ * \return 0 on success or a negative error code
*/
/**
diff --git a/src/libcamera/request.cpp b/src/libcamera/request.cpp
index d76db24de0e279e5..a219b061d8814001 100644
--- a/src/libcamera/request.cpp
+++ b/src/libcamera/request.cpp
@@ -43,7 +43,7 @@ Request::Request(Camera *camera)
/**
* \brief Set the streams to capture with associated buffers
* \param[in] streamMap The map of streams to buffers
- * \return 0 on success or a negative error code otherwise
+ * \return 0 on success or a negative error code
* \retval -EBUSY Buffers have already been set
*/
int Request::setBuffers(const std::map<Stream *, Buffer *> &streamMap)
diff --git a/src/libcamera/v4l2_device.cpp b/src/libcamera/v4l2_device.cpp
index 24e115554a997325..8024e041f9b8124a 100644
--- a/src/libcamera/v4l2_device.cpp
+++ b/src/libcamera/v4l2_device.cpp
@@ -247,7 +247,7 @@ V4L2Device::~V4L2Device()
/**
* \brief Open a V4L2 device and query its capabilities
- * \return 0 on success, or a negative error code otherwise
+ * \return 0 on success or a negative error code
*/
int V4L2Device::open()
{
@@ -365,7 +365,7 @@ 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 for success, a negative error code otherwise
+ * \return 0 on success or a negative error code
*/
int V4L2Device::getFormat(V4L2DeviceFormat *format)
{
@@ -380,7 +380,7 @@ int V4L2Device::getFormat(V4L2DeviceFormat *format)
* Apply the supplied \a format to the device, and return the actually
* applied format parameters, as \ref V4L2Device::getFormat would do.
*
- * \return 0 for success, a negative error code otherwise
+ * \return 0 on success or a negative error code
*/
int V4L2Device::setFormat(V4L2DeviceFormat *format)
{
@@ -541,7 +541,7 @@ int V4L2Device::requestBuffers(unsigned int count)
* \brief Request buffers to be allocated from the device and stored in the
* buffer pool provided.
* \param[out] pool BufferPool to populate with buffers
- * \return 0 on success or a negative error code otherwise
+ * \return 0 on success or a negative error code
*/
int V4L2Device::exportBuffers(BufferPool *pool)
{
@@ -645,7 +645,7 @@ int V4L2Device::createPlane(Buffer *buffer, unsigned int planeIndex,
/**
* \brief Import the externally allocated \a pool of buffers
* \param[in] pool BufferPool of buffers to import
- * \return 0 on success or a negative error code otherwise
+ * \return 0 on success or a negative error code
*/
int V4L2Device::importBuffers(BufferPool *pool)
{
@@ -697,7 +697,7 @@ int V4L2Device::releaseBuffers()
* \todo Support output devices (bytesused, ...)
* \todo Support imported buffers (dmabuf fd)
*
- * \return 0 on success or a negative error number otherwise
+ * \return 0 on success or a negative error code
*/
int V4L2Device::queueBuffer(Buffer *buffer)
{
@@ -830,7 +830,7 @@ void V4L2Device::bufferAvailable(EventNotifier *notifier)
/**
* \brief Start the video stream
*
- * \return 0 on success or a negative error code otherwise
+ * \return 0 on success or a negative error code
*/
int V4L2Device::streamOn()
{
@@ -852,7 +852,7 @@ int V4L2Device::streamOn()
*
* \todo Ensure completion notifications are sent for all queued buffers
*
- * \return 0 on success or a negative error code otherwise
+ * \return 0 on success or a negative error code
*/
int V4L2Device::streamOff()
{
diff --git a/src/libcamera/v4l2_subdevice.cpp b/src/libcamera/v4l2_subdevice.cpp
index b436f73cc75fe307..b31eac2ed9bd2502 100644
--- a/src/libcamera/v4l2_subdevice.cpp
+++ b/src/libcamera/v4l2_subdevice.cpp
@@ -95,7 +95,7 @@ V4L2Subdevice::V4L2Subdevice(const MediaEntity *entity)
/**
* \brief Open a V4L2 subdevice
*
- * \return 0 on success, a negative error code otherwise
+ * \return 0 on success or a negative error code
*/
int V4L2Subdevice::open()
{
@@ -152,7 +152,7 @@ void V4L2Subdevice::close()
* \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
+ * \return 0 on success or a negative error code
*/
int V4L2Subdevice::setCrop(unsigned int pad, Rectangle *rect)
{
@@ -164,7 +164,7 @@ int V4L2Subdevice::setCrop(unsigned int pad, Rectangle *rect)
* \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
+ * \return 0 on success or a negative error code
*/
int V4L2Subdevice::setCompose(unsigned int pad, Rectangle *rect)
{
@@ -176,7 +176,7 @@ int V4L2Subdevice::setCompose(unsigned int pad, Rectangle *rect)
* \param[in] pad The 0-indexed pad number the format is to be retrieved from
* \param[out] format The image bus format
*
- * \return 0 for success, a negative error code otherwise
+ * \return 0 on success or a negative error code
*/
int V4L2Subdevice::getFormat(unsigned int pad, V4L2SubdeviceFormat *format)
{
@@ -209,7 +209,7 @@ int V4L2Subdevice::getFormat(unsigned int pad, V4L2SubdeviceFormat *format)
* actually applied format parameters, as \ref V4L2Subdevice::getFormat would
* do.
*
- * \return 0 for success, a negative error code otherwise
+ * \return 0 on success or a negative error code
*/
int V4L2Subdevice::setFormat(unsigned int pad, V4L2SubdeviceFormat *format)
{
--
2.20.1
More information about the libcamera-devel
mailing list