[libcamera-devel] [PATCH 3/8] libcamera: camera: document return values for application facing functions

[Niklas Söderlund]

In preparation for adding a state machine to control access to the
functions facing the application document the error codes which will be
returned once it's in place.

Signed-off-by: Niklas Söderlund <niklas.soderlund at ragnatech.se>
---
 src/libcamera/camera.cpp | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/src/libcamera/camera.cpp b/src/libcamera/camera.cpp
index e2372fea31e2921a..d4258fe3c7551af3 100644
--- a/src/libcamera/camera.cpp
+++ b/src/libcamera/camera.cpp
@@ -158,6 +158,7 @@ void Camera::disconnect()
  * \todo Implement exclusive access across processes.
  *
  * \return 0 on success or a negative error code
+ * \retval -EBUSY The camera is not free and can't be acquired by the caller.
  */
 int Camera::acquire()
 {
@@ -236,9 +237,8 @@ Camera::streamConfiguration(std::vector<Stream *> &streams)
  * to calling this function, otherwise an -EACCES error will be returned.
  *
  * \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
+ * \retval -EACCES The camera is not in a state where it can be configured.
+ * \retval -EINVAL The configuration is not valid.
  */
 int Camera::configureStreams(std::map<Stream *, StreamConfiguration> &config)
 {
@@ -279,6 +279,8 @@ int Camera::configureStreams(std::map<Stream *, StreamConfiguration> &config)
 /**
  * \brief Allocate buffers for all configured streams
  * \return 0 on success or a negative error code
+ * \retval -EACCES The camera is not in a state where it can allocate buffers.
+ * \retval -EINVAL The configuration is not valid.
  */
 int Camera::allocateBuffers()
 {
@@ -330,6 +332,7 @@ void Camera::freeBuffers()
  * responsible for either queueing the request or deleting it.
  *
  * \return A pointer to the newly created request, or nullptr on error
+ * \retval -EACCES The camera is not in a state where requests can be created.
  */
 Request *Camera::createRequest()
 {
@@ -351,6 +354,7 @@ Request *Camera::createRequest()
  * automatically after it completes.
  *
  * \return 0 on success or a negative error code
+ * \retval -EACCES The camera is not running so requests can't be queued.
  */
 int Camera::queueRequest(Request *request)
 {
@@ -377,6 +381,7 @@ int Camera::queueRequest(Request *request)
  * until the capture session is terminated with \a stop().
  *
  * \return 0 on success or a negative error code
+ * \retval -EACCES The camera is not in a state where it can be started.
  */
 int Camera::start()
 {
@@ -396,6 +401,7 @@ int Camera::start()
  * requests are cancelled and complete synchronously in an error state.
  *
  * \return 0 on success or a negative error code
+ * \retval -EACCES The camera is not running so can't be stopped.
  */
 int Camera::stop()
 {
-- 
2.20.1