{"id":623,"url":"https://patchwork.libcamera.org/api/1.1/patches/623/?format=json","web_url":"https://patchwork.libcamera.org/patch/623/","project":{"id":1,"url":"https://patchwork.libcamera.org/api/1.1/projects/1/?format=json","name":"libcamera","link_name":"libcamera","list_id":"libcamera_core","list_email":"libcamera-devel@lists.libcamera.org","web_url":"","scm_url":"","webscm_url":""},"msgid":"<20190226021857.28255-3-niklas.soderlund@ragnatech.se>","date":"2019-02-26T02:18:51","name":"[libcamera-devel,2/8] libcamera: align the documentation for numeric error codes","commit_ref":null,"pull_url":null,"state":"superseded","archived":false,"hash":"2b1f58ecb9762b1680e2ea9dbaf8909342a8d826","submitter":{"id":5,"url":"https://patchwork.libcamera.org/api/1.1/people/5/?format=json","name":"Niklas Söderlund","email":"niklas.soderlund@ragnatech.se"},"delegate":null,"mbox":"https://patchwork.libcamera.org/patch/623/mbox/","series":[{"id":192,"url":"https://patchwork.libcamera.org/api/1.1/series/192/?format=json","web_url":"https://patchwork.libcamera.org/project/libcamera/list/?series=192","date":"2019-02-26T02:18:50","name":"libcamera: improve validation of camera operations","version":1,"mbox":"https://patchwork.libcamera.org/series/192/mbox/"}],"comments":"https://patchwork.libcamera.org/api/patches/623/comments/","check":"pending","checks":"https://patchwork.libcamera.org/api/patches/623/checks/","tags":{},"headers":{"Return-Path":"","Received":["from bin-mail-out-05.binero.net (bin-mail-out-05.binero.net\n\t[195.74.38.228])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 62A56610BB\n\tfor ;\n\tTue, 26 Feb 2019 03:19:17 +0100 (CET)","from bismarck.berto.se (unknown [89.233.230.99])\n\tby bin-vsp-out-02.atm.binero.net (Halon) with ESMTPA\n\tid e98efad2-396c-11e9-985a-005056917f90;\n\tTue, 26 Feb 2019 03:19:15 +0100 (CET)"],"X-Halon-ID":"e98efad2-396c-11e9-985a-005056917f90","Authorized-sender":"niklas@soderlund.pp.se","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","Content-Type":"text/plain; charset=UTF-8","Content-Transfer-Encoding":"8bit","Subject":"[libcamera-devel] [PATCH 2/8] libcamera: align the documentation\n\tfor numeric error codes","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.23","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","X-List-Received-Date":"Tue, 26 Feb 2019 02:19:17 -0000"},"content":"Rapid growth of the library have resulted in slightly different wording\nto document that a function returns 0 on success or a negative error\ncode. Align all different variations.\n\nSigned-off-by: Niklas Söderlund \n---\n src/libcamera/buffer.cpp | 6 +++---\n src/libcamera/camera.cpp | 12 ++++++------\n src/libcamera/camera_manager.cpp | 2 +-\n src/libcamera/device_enumerator.cpp | 7 +++----\n src/libcamera/media_device.cpp | 8 ++++----\n src/libcamera/media_object.cpp | 5 ++---\n src/libcamera/pipeline_handler.cpp | 10 +++++-----\n src/libcamera/request.cpp | 2 +-\n src/libcamera/v4l2_device.cpp | 16 ++++++++--------\n src/libcamera/v4l2_subdevice.cpp | 10 +++++-----\n 10 files changed, 38 insertions(+), 40 deletions(-)","diff":"diff --git a/src/libcamera/buffer.cpp b/src/libcamera/buffer.cpp\nindex 9ec372c2981b5b02..f7c5f0e6a3fe0e55 100644\n--- a/src/libcamera/buffer.cpp\n+++ b/src/libcamera/buffer.cpp\n@@ -71,7 +71,7 @@ Plane::~Plane()\n * The \\a fd dmabuf file handle is duplicated and stored. The caller may close\n * the original file handle.\n *\n- * \\return 0 on success or a negative error value otherwise.\n+ * \\return 0 on success or a negative error code\n */\n int Plane::setDmabuf(int fd, unsigned int length)\n {\n@@ -106,7 +106,7 @@ int Plane::setDmabuf(int fd, unsigned int length)\n *\n * \\sa setDmaBuf()\n *\n- * \\return 0 on success or a negative error value otherwise.\n+ * \\return 0 on success or a negative error code\n */\n int Plane::mmap()\n {\n@@ -133,7 +133,7 @@ int Plane::mmap()\n *\n * Unmap the memory mapped by an earlier call to mmap().\n *\n- * \\return 0 on success or a negative error value otherwise.\n+ * \\return 0 on success or a negative error code\n */\n int Plane::munmap()\n {\ndiff --git a/src/libcamera/camera.cpp b/src/libcamera/camera.cpp\nindex 6409d10ff88b2189..e2372fea31e2921a 100644\n--- a/src/libcamera/camera.cpp\n+++ b/src/libcamera/camera.cpp\n@@ -157,7 +157,7 @@ void Camera::disconnect()\n *\n * \\todo Implement exclusive access across processes.\n *\n- * \\return 0 on success or a negative error code on error.\n+ * \\return 0 on success or a negative error code\n */\n int Camera::acquire()\n {\n@@ -235,7 +235,7 @@ Camera::streamConfiguration(std::vector &streams)\n * Exclusive access to the camera shall be ensured by a call to acquire() prior\n * to calling this function, otherwise an -EACCES error will be returned.\n *\n- * \\return 0 on success or a negative error code on error.\n+ * \\return 0 on success or a negative error code\n * \\retval -ENODEV The camera is not connected to any hardware\n * \\retval -EACCES The user has not acquired exclusive access to the camera\n * \\retval -EINVAL The configuration is not valid\n@@ -278,7 +278,7 @@ int Camera::configureStreams(std::map &config)\n \n /**\n * \\brief Allocate buffers for all configured streams\n- * \\return 0 on success or a negative error code otherwise\n+ * \\return 0 on success or a negative error code\n */\n int Camera::allocateBuffers()\n {\n@@ -350,7 +350,7 @@ Request *Camera::createRequest()\n * Ownership of the request is transferred to the camera. It will be deleted\n * automatically after it completes.\n *\n- * \\return 0 on success or a negative error code on error\n+ * \\return 0 on success or a negative error code\n */\n int Camera::queueRequest(Request *request)\n {\n@@ -376,7 +376,7 @@ int Camera::queueRequest(Request *request)\n * can queue requests to the camera to process and return to the application\n * until the capture session is terminated with \\a stop().\n *\n- * \\return 0 on success or a negative error code on error\n+ * \\return 0 on success or a negative error code\n */\n int Camera::start()\n {\n@@ -395,7 +395,7 @@ int Camera::start()\n * This method stops capturing and processing requests immediately. All pending\n * requests are cancelled and complete synchronously in an error state.\n *\n- * \\return 0 on success or a negative error code on error\n+ * \\return 0 on success or a negative error code\n */\n int Camera::stop()\n {\ndiff --git a/src/libcamera/camera_manager.cpp b/src/libcamera/camera_manager.cpp\nindex f90201ade18b61dd..6878cc7e26b24ca4 100644\n--- a/src/libcamera/camera_manager.cpp\n+++ b/src/libcamera/camera_manager.cpp\n@@ -74,7 +74,7 @@ CameraManager::~CameraManager()\n * interact with cameras in the system until either the camera manager\n * is stopped or the camera is unplugged from the system.\n *\n- * \\return 0 on successful start, or a negative error code otherwise\n+ * \\return 0 on success or a negative error code\n */\n int CameraManager::start()\n {\ndiff --git a/src/libcamera/device_enumerator.cpp b/src/libcamera/device_enumerator.cpp\nindex 66819f077c16c721..b35ac2bb626ec3c6 100644\n--- a/src/libcamera/device_enumerator.cpp\n+++ b/src/libcamera/device_enumerator.cpp\n@@ -178,7 +178,7 @@ DeviceEnumerator::~DeviceEnumerator()\n /**\n * \\fn DeviceEnumerator::init()\n * \\brief Initialize the enumerator\n- * \\return 0 on success, or a negative error code otherwise\n+ * \\return 0 on success or a negative error code\n * \\retval -EBUSY the enumerator has already been initialized\n * \\retval -ENODEV the enumerator can't enumerate devices\n */\n@@ -195,7 +195,7 @@ DeviceEnumerator::~DeviceEnumerator()\n * with a warning message logged, without returning an error. Only errors that\n * prevent enumeration altogether shall be fatal.\n *\n- * \\return 0 on success, or a negative error code on fatal errors.\n+ * \\return 0 on success or a negative error code\n */\n \n /**\n@@ -206,8 +206,7 @@ DeviceEnumerator::~DeviceEnumerator()\n * and look up device nodes associated with all entities. Store the media device\n * in the internal list for later matching with pipeline handlers.\n *\n- * \\return 0 on success, or a negative error code if the media device can't be\n- * created or populated\n+ * \\return 0 on success or a negative error code\n */\n int DeviceEnumerator::addDevice(const std::string &deviceNode)\n {\ndiff --git a/src/libcamera/media_device.cpp b/src/libcamera/media_device.cpp\nindex 800ed330fe6d8d6f..4f494e316867a55c 100644\n--- a/src/libcamera/media_device.cpp\n+++ b/src/libcamera/media_device.cpp\n@@ -136,7 +136,7 @@ bool MediaDevice::acquire()\n *\n * If the device is already open the function returns -EBUSY.\n *\n- * \\return 0 on success or a negative error code otherwise\n+ * \\return 0 on success or a negative error code\n */\n int MediaDevice::open()\n {\n@@ -206,7 +206,7 @@ void MediaDevice::close()\n * while pads are accessible from the entity they belong to and links from the\n * pads they connect.\n *\n- * \\return 0 on success, a negative error code otherwise\n+ * \\return 0 on success or a negative error code\n */\n int MediaDevice::populate()\n {\n@@ -405,7 +405,7 @@ MediaLink *MediaDevice::link(const MediaPad *source, const MediaPad *sink)\n * Disable all the media device links, clearing the MEDIA_LNK_FL_ENABLED flag\n * on links which are not flagged as IMMUTABLE.\n *\n- * \\return 0 on success, or a negative error code otherwise\n+ * \\return 0 on success or a negative error code\n */\n int MediaDevice::disableLinks()\n {\n@@ -705,7 +705,7 @@ void MediaDevice::fixupEntityFlags(struct media_v2_entity *entity)\n *\n * \\sa MediaLink::setEnabled(bool enable)\n *\n- * \\return 0 on success, or a negative error code otherwise\n+ * \\return 0 on success or a negative error code\n */\n int MediaDevice::setupLink(const MediaLink *link, unsigned int flags)\n {\ndiff --git a/src/libcamera/media_object.cpp b/src/libcamera/media_object.cpp\nindex f6abcd8676a3866d..79126124caf98497 100644\n--- a/src/libcamera/media_object.cpp\n+++ b/src/libcamera/media_object.cpp\n@@ -111,7 +111,7 @@ LOG_DECLARE_CATEGORY(MediaDevice)\n * Enabling a link establishes a data connection between two pads, while\n * disabling it interrupts that connection.\n *\n- * \\return 0 on success, or a negative error code otherwise\n+ * \\return 0 on success or a negative error code\n */\n int MediaLink::setEnabled(bool enable)\n {\n@@ -337,8 +337,7 @@ const MediaPad *MediaEntity::getPadById(unsigned int id) const\n /**\n * \\brief Set the path to the device node for the associated interface\n * \\param deviceNode The interface device node path associated with this entity\n- * \\return 0 on success, or a negative error code if the device node can't be\n- * accessed\n+ * \\return 0 on success or a negative error code\n */\n int MediaEntity::setDeviceNode(const std::string &deviceNode)\n {\ndiff --git a/src/libcamera/pipeline_handler.cpp b/src/libcamera/pipeline_handler.cpp\nindex dad0a2964486c5d4..0a858fbe13257c7f 100644\n--- a/src/libcamera/pipeline_handler.cpp\n+++ b/src/libcamera/pipeline_handler.cpp\n@@ -144,7 +144,7 @@ PipelineHandler::~PipelineHandler()\n * configuration of a subset of the streams can't be satisfied, the\n * whole configuration is considered invalid.\n *\n- * \\return 0 on success or a negative error code on error.\n+ * \\return 0 on success or a negative error code\n */\n \n /**\n@@ -158,7 +158,7 @@ PipelineHandler::~PipelineHandler()\n *\n * The intended caller of this method is the Camera class.\n *\n- * \\return 0 on success or a negative error code on error\n+ * \\return 0 on success or a negative error code\n */\n \n /**\n@@ -172,7 +172,7 @@ PipelineHandler::~PipelineHandler()\n *\n * The intended caller of this method is the Camera class.\n *\n- * \\return 0 on success or a negative error code on error\n+ * \\return 0 on success or a negative error code\n */\n \n /**\n@@ -185,7 +185,7 @@ PipelineHandler::~PipelineHandler()\n * class which will in turn be called from the application to indicate that it\n * has configured the streams and is ready to capture.\n *\n- * \\return 0 on success or a negative error code on error\n+ * \\return 0 on success or a negative error code\n */\n \n /**\n@@ -211,7 +211,7 @@ PipelineHandler::~PipelineHandler()\n * parameters will be applied to the frames captured in the buffers provided in\n * the request.\n *\n- * \\return 0 on success or a negative error code on error\n+ * \\return 0 on success or a negative error code\n */\n \n /**\ndiff --git a/src/libcamera/request.cpp b/src/libcamera/request.cpp\nindex d76db24de0e279e5..a219b061d8814001 100644\n--- a/src/libcamera/request.cpp\n+++ b/src/libcamera/request.cpp\n@@ -43,7 +43,7 @@ Request::Request(Camera *camera)\n /**\n * \\brief Set the streams to capture with associated buffers\n * \\param[in] streamMap The map of streams to buffers\n- * \\return 0 on success or a negative error code otherwise\n+ * \\return 0 on success or a negative error code\n * \\retval -EBUSY Buffers have already been set\n */\n int Request::setBuffers(const std::map &streamMap)\ndiff --git a/src/libcamera/v4l2_device.cpp b/src/libcamera/v4l2_device.cpp\nindex 24e115554a997325..8024e041f9b8124a 100644\n--- a/src/libcamera/v4l2_device.cpp\n+++ b/src/libcamera/v4l2_device.cpp\n@@ -247,7 +247,7 @@ V4L2Device::~V4L2Device()\n \n /**\n * \\brief Open a V4L2 device and query its capabilities\n- * \\return 0 on success, or a negative error code otherwise\n+ * \\return 0 on success or a negative error code\n */\n int V4L2Device::open()\n {\n@@ -365,7 +365,7 @@ std::string V4L2Device::logPrefix() const\n * \\brief Retrieve the image format set on the V4L2 device\n * \\param[out] format The image format applied on the device\n *\n- * \\return 0 for success, a negative error code otherwise\n+ * \\return 0 on success or a negative error code\n */\n int V4L2Device::getFormat(V4L2DeviceFormat *format)\n {\n@@ -380,7 +380,7 @@ int V4L2Device::getFormat(V4L2DeviceFormat *format)\n * Apply the supplied \\a format to the device, and return the actually\n * applied format parameters, as \\ref V4L2Device::getFormat would do.\n *\n- * \\return 0 for success, a negative error code otherwise\n+ * \\return 0 on success or a negative error code\n */\n int V4L2Device::setFormat(V4L2DeviceFormat *format)\n {\n@@ -541,7 +541,7 @@ int V4L2Device::requestBuffers(unsigned int count)\n * \\brief Request buffers to be allocated from the device and stored in the\n * buffer pool provided.\n * \\param[out] pool BufferPool to populate with buffers\n- * \\return 0 on success or a negative error code otherwise\n+ * \\return 0 on success or a negative error code\n */\n int V4L2Device::exportBuffers(BufferPool *pool)\n {\n@@ -645,7 +645,7 @@ int V4L2Device::createPlane(Buffer *buffer, unsigned int planeIndex,\n /**\n * \\brief Import the externally allocated \\a pool of buffers\n * \\param[in] pool BufferPool of buffers to import\n- * \\return 0 on success or a negative error code otherwise\n+ * \\return 0 on success or a negative error code\n */\n int V4L2Device::importBuffers(BufferPool *pool)\n {\n@@ -697,7 +697,7 @@ int V4L2Device::releaseBuffers()\n * \\todo Support output devices (bytesused, ...)\n * \\todo Support imported buffers (dmabuf fd)\n *\n- * \\return 0 on success or a negative error number otherwise\n+ * \\return 0 on success or a negative error code\n */\n int V4L2Device::queueBuffer(Buffer *buffer)\n {\n@@ -830,7 +830,7 @@ void V4L2Device::bufferAvailable(EventNotifier *notifier)\n /**\n * \\brief Start the video stream\n *\n- * \\return 0 on success or a negative error code otherwise\n+ * \\return 0 on success or a negative error code\n */\n int V4L2Device::streamOn()\n {\n@@ -852,7 +852,7 @@ int V4L2Device::streamOn()\n *\n * \\todo Ensure completion notifications are sent for all queued buffers\n *\n- * \\return 0 on success or a negative error code otherwise\n+ * \\return 0 on success or a negative error code\n */\n int V4L2Device::streamOff()\n {\ndiff --git a/src/libcamera/v4l2_subdevice.cpp b/src/libcamera/v4l2_subdevice.cpp\nindex b436f73cc75fe307..b31eac2ed9bd2502 100644\n--- a/src/libcamera/v4l2_subdevice.cpp\n+++ b/src/libcamera/v4l2_subdevice.cpp\n@@ -95,7 +95,7 @@ V4L2Subdevice::V4L2Subdevice(const MediaEntity *entity)\n /**\n * \\brief Open a V4L2 subdevice\n *\n- * \\return 0 on success, a negative error code otherwise\n+ * \\return 0 on success or a negative error code\n */\n int V4L2Subdevice::open()\n {\n@@ -152,7 +152,7 @@ void V4L2Subdevice::close()\n * \\param[in] pad The 0-indexed pad number the rectangle is to be applied to\n * \\param[inout] rect The rectangle describing crop target area\n *\n- * \\return 0 on success, or a negative error code otherwise\n+ * \\return 0 on success or a negative error code\n */\n int V4L2Subdevice::setCrop(unsigned int pad, Rectangle *rect)\n {\n@@ -164,7 +164,7 @@ int V4L2Subdevice::setCrop(unsigned int pad, Rectangle *rect)\n * \\param[in] pad The 0-indexed pad number the rectangle is to be applied to\n * \\param[inout] rect The rectangle describing the compose target area\n *\n- * \\return 0 on success, or a negative error code otherwise\n+ * \\return 0 on success or a negative error code\n */\n int V4L2Subdevice::setCompose(unsigned int pad, Rectangle *rect)\n {\n@@ -176,7 +176,7 @@ int V4L2Subdevice::setCompose(unsigned int pad, Rectangle *rect)\n * \\param[in] pad The 0-indexed pad number the format is to be retrieved from\n * \\param[out] format The image bus format\n *\n- * \\return 0 for success, a negative error code otherwise\n+ * \\return 0 on success or a negative error code\n */\n int V4L2Subdevice::getFormat(unsigned int pad, V4L2SubdeviceFormat *format)\n {\n@@ -209,7 +209,7 @@ int V4L2Subdevice::getFormat(unsigned int pad, V4L2SubdeviceFormat *format)\n * actually applied format parameters, as \\ref V4L2Subdevice::getFormat would\n * do.\n *\n- * \\return 0 for success, a negative error code otherwise\n+ * \\return 0 on success or a negative error code\n */\n int V4L2Subdevice::setFormat(unsigned int pad, V4L2SubdeviceFormat *format)\n {\n","prefixes":["libcamera-devel","2/8"]}