Add extensive documentation

1 files changed, 102 insertions, 15 deletions

diff --git a/src/uca-cam.h b/src/uca-cam.h
index 367b7ab..80bf4e7 100644
--- a/src/uca-cam.h
+++ b/src/uca-cam.h
@@ -7,17 +7,30 @@
 extern "C" {
 #endif
 
+/**
+ * \file uca-cam.h
+ * \brief Abstract camera model
+ *
+ * The uca_camera_t structure represents a common interface for cameras regardless of
+ * their connectivity. Each camera that adheres to this model must provide an
+ * initialization function implementing uca_cam_init() that probes the device
+ * and sets all function pointers to their respective implementations.
+ */
+
 struct uca_camera_t;
 struct uca_grabber_t;
 struct uca_property_t;
 
 enum uca_property_ids;
 
+/**
+ * Describes the current state of the camera.
+ */
 enum uca_cam_state {
-    UCA_CAM_ERROR,
-    UCA_CAM_CONFIGURABLE,
-    UCA_CAM_ARMED,
-    UCA_CAM_RECORDING,
+    UCA_CAM_ERROR,          /**< Camera is not working correctly */
+    UCA_CAM_CONFIGURABLE,   /**< Camera can be configured and is not recording */
+    UCA_CAM_ARMED,          /**< Camera is ready for recording */
+    UCA_CAM_RECORDING,      /**< Camera is currently recording */
 };
 
 
@@ -26,11 +39,25 @@ enum uca_cam_state {
  */
 
 /**
- * \brief Allocates buffer memory for the internal frame grabber
- * \param[in] n_buffers Number of sub-buffers with size frame_width*frame_height
+ * Allocates buffer memory for the internal frame grabber.
+ *
+ * The allocation is just a hint to the underlying camera driver. It might
+ * ignore this or pass this information on to a related frame grabber.
+ *
+ * \param[in] cam A camera structure.
+ * 
+ * \param[in] n_buffers Number of sub-buffers with size frame_width*frame_height.
  */
 uint32_t uca_cam_alloc(struct uca_camera_t *cam, uint32_t n_buffers);
 
+/**
+ * Retrieve current state of the camera.
+ *
+ * \param[in] cam A camera structure.
+ *
+ * \return A value from the uca_cam_state enum representing the current state of
+ *   the camera.
+ */
 enum uca_cam_state uca_cam_get_state(struct uca_camera_t *cam);
 
 
@@ -39,41 +66,68 @@ enum uca_cam_state uca_cam_get_state(struct uca_camera_t *cam);
  */
 
 /**
- * \brief Camera probing and initialization
- * \return UCA_ERR_INIT_NOT_FOUND if camera is not found or could not be initialized
+ * Function pointer for camera probing and initialization. 
+ *
+ * \param[out] cam On success, *cam holds the newly created uca_camera_t
+ *   structure.
+ *
+ * \param[in] grabber Grabber structure to access the cam. Can be NULL to
+ *   specify devices without frame grabber access.
+ *
+ * \return 
+ *   UCA_ERR_INIT_NOT_FOUND if camera is not found or could not be initialized
+ *
+ * \note This is a private function and should be called exclusively by uca_init().
  */
 typedef uint32_t (*uca_cam_init) (struct uca_camera_t **cam, struct uca_grabber_t *grabber);
 
 /**
- * \brief Free camera resouces
+ * \brief Function pointer to free camera resources.
+ *
+ * \param[in] cam The camera to close.
+ *
+ * \note This is a private function and should be called exclusively by uca_init().
  */
 typedef uint32_t (*uca_cam_destroy) (struct uca_camera_t *cam);
 
 /**
- * \brief Set a property
+ * Function pointer to set a camera property.
+ *
+ * \param[in] cam The camera whose properties are to be set.
+ *
  * \param[in] property ID of the property as defined in XXX
+ *
  * \param[out] data Where to read the property's value from
+ *
  * \return UCA_ERR_PROP_INVALID if property is not supported on the camera or
- * UCA_ERR_PROP_VALUE_OUT_OF_RANGE if value cannot be set.
+ *   UCA_ERR_PROP_VALUE_OUT_OF_RANGE if value cannot be set.
  */
 typedef uint32_t (*uca_cam_set_property) (struct uca_camera_t *cam, enum uca_property_ids property, void *data);
 
 /**
- * \brief Get a property
+ * Function pointer to get a property.
+ *
+ * \param[in] cam The camera whose properties are to be retrieved.
+ *
  * \param[in] property ID of the property as defined in XXX
+ *
  * \param[out] data Where to store the property's value
+ *
  * \return UCA_ERR_PROP_INVALID if property is not supported on the camera
  */
 typedef uint32_t (*uca_cam_get_property) (struct uca_camera_t *cam, enum uca_property_ids property, void *data);
 
 /**
- * \brief Begin recording
+ * Begin recording.
  *
  * Usually this also involves the frame acquisition of the frame grabber but is
  * hidden by this function.
  */
 typedef uint32_t (*uca_cam_start_recording) (struct uca_camera_t *cam);
 
+/**
+ * Stop recording.
+ */
 typedef uint32_t (*uca_cam_stop_recording) (struct uca_camera_t *cam);
 
 /**
@@ -88,20 +142,53 @@ typedef uint32_t (*uca_cam_grab) (struct uca_camera_t *cam, char *buffer);
 
 
 struct uca_camera_t {
+    /**
+     * Points to the next available camera in a linked-list fashion.
+     *
+     * End of list is specified with next == NULL.
+     */
     struct uca_camera_t     *next;
 
     /* Function pointers to camera-specific methods */
+    /**
+     * Method to set a property.
+     * \see uca_cam_set_property
+     */
     uca_cam_set_property    set_property;
+
+    /**
+     * Method to get a property.
+     * \see uca_cam_get_property
+     */
     uca_cam_get_property    get_property;
+
+    /**
+     * Method to start recording.
+     * \see uca_cam_start_recording
+     */
     uca_cam_start_recording start_recording;
+
+    /**
+     * Method to stop recording.
+     * \see uca_cam_stop_recording
+     */
     uca_cam_stop_recording  stop_recording;
+
+    /**
+     * Method to grab a frame.
+     * \see uca_cam_grab
+     */
     uca_cam_grab            grab;
 
     /* Private */
+    /**
+     * Method to close the camera.
+     * \see uca_cam_destroy
+     */
     uca_cam_destroy         destroy;
 
-    struct uca_grabber_t    *grabber;
-    enum uca_cam_state      state;
+    struct uca_grabber_t    *grabber;   /**< grabber associated with this camera */
+    enum uca_cam_state      state;      /**< camera state */
     uint32_t                frame_width;
     uint32_t                frame_height;