From patchwork Tue Feb 26 02:18:51 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Niklas_S=C3=B6derlund?= X-Patchwork-Id: 623 Return-Path: Received: from bin-mail-out-05.binero.net (bin-mail-out-05.binero.net [195.74.38.228]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 62A56610BB for ; Tue, 26 Feb 2019 03:19:17 +0100 (CET) X-Halon-ID: e98efad2-396c-11e9-985a-005056917f90 Authorized-sender: niklas@soderlund.pp.se Received: from bismarck.berto.se (unknown [89.233.230.99]) by bin-vsp-out-02.atm.binero.net (Halon) with ESMTPA id e98efad2-396c-11e9-985a-005056917f90; Tue, 26 Feb 2019 03:19:15 +0100 (CET) From: =?utf-8?q?Niklas_S=C3=B6derlund?= To: libcamera-devel@lists.libcamera.org Date: Tue, 26 Feb 2019 03:18:51 +0100 Message-Id: <20190226021857.28255-3-niklas.soderlund@ragnatech.se> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190226021857.28255-1-niklas.soderlund@ragnatech.se> References: <20190226021857.28255-1-niklas.soderlund@ragnatech.se> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH 2/8] libcamera: align the documentation for numeric error codes X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 26 Feb 2019 02:19:17 -0000 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 Reviewed-by: Jacopo Mondi Acked-by: Laurent Pinchart --- 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 &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 &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 &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) {