Add descriptive comments to camera device and properties headers (#35)

This adds some missing header doc comments and updates other to clarify
what some struct members are more exactly.

Closes #27

src/acquire-device-kit/device/kit/camera.h

@@ -9,25 +9,48 @@ extern "C"
 {
 #endif
 
+    /// @brief Represents and allows control of a camera device.
     struct Camera
     {
         struct Device device;
         enum DeviceState state;
 
+        /// @brief Attempts to set the given properties on the given camera.
+        /// @details Setting properties can partially succeed depending on
+        ///          other property values or the state of the camera.
+        ///          If you want to be certain that a specific property was
+        ///          actually used, you should call get afterwards to check
+        ///          that property value.
         enum DeviceStatusCode (*set)(struct Camera*,
                                      struct CameraProperties* settings);
+
+        /// @brief Fills out the given properties from the given camera.
         enum DeviceStatusCode (*get)(const struct Camera*,
                                      struct CameraProperties* settings);
+
+        /// @brief Fills out the given property metadata from the given camera.
+        /// @details These metadata or capabilities may depend on the camera's
+        ///          current property values.
         enum DeviceStatusCode (*get_meta)(const struct Camera*,
                                           struct CameraPropertyMetadata* meta);
+
+        /// @brief The shape of the next frame that the camera will capture.
         enum DeviceStatusCode (*get_shape)(const struct Camera*,
                                            struct ImageShape* shape);
+        /// @brief Starts acquiring frames.
         enum DeviceStatusCode (*start)(struct Camera*);
+
+        /// @brief Stops acquiring frames.
+        /// @details This instructs the camera to stop and may block until it
+        ///          actually has stopped acquiring frames.
+        ///          The camera should also be restartable after calling this
+        ///          (i.e. one call of start after one call of stop should succeed).
         enum DeviceStatusCode (*stop)(struct Camera*);
 
-        // Fire the software trigger if it's enabled.
+        /// @brief Execute the software trigger if it's enabled.
         enum DeviceStatusCode (*execute_trigger)(struct Camera*);
 
+        /// @brief Gets the next frame from the camera.
         enum DeviceStatusCode (*get_frame)(struct Camera*,
                                            void* im,
                                            size_t* nbytes,

src/acquire-device-properties/device/props/camera.h

@@ -11,31 +11,61 @@ extern "C"
 {
 #endif
 
+    /// @brief Stores the properties of a camera.
+    /// @details Can be populated with values from a camera or
+    ///          can be filled out to define new values that a camera should adopt.
     struct CameraProperties
     {
+        /// @brief Exposure time of a frame in microseconds.
+        /// @details Acquire assumes that exposure is always manually specified by this period of time.
+        ///          It does not currently support auto-exposure or durations defined by trigger widths.
         float exposure_time_us;
+
         float line_interval_us;
         enum Direction readout_direction;
+
+        /// @brief Binning or downsample factor.
+        /// @details Determines how many pixels in each spatial dimension on the
+        ///          sensor are aggregated to form pixels in an image.
+        ///          For example, if we have a sensor of size 1920x1200 and a binning
+        ///          factor of 2, one image should be 960x600.
         uint8_t binning;
+
+        /// @brief Type of each image pixel or sample.
         enum SampleType pixel_type;
+
+        /// @brief Offset of the region of interest on the sensor from its top-left corner.
+        /// @details Each value represents a number of aggregated pixels in the
+        ///          frame after binning has been applied.
         struct camera_properties_offset_s
         {
             uint32_t x, y;
         } offset;
+
+        /// @brief Shape or size of the region of interest on the sensor.
+        /// @details Each value represents a number of aggregated pixels in the
+        ///          frame after binning has been applied.
         struct camera_properties_shape_s
         {
             uint32_t x, y;
         } shape;
+
+        /// @brief State of the camera's input triggers.
         struct camera_properties_input_triggers_s
         {
             struct Trigger acquisition_start, frame_start, exposure;
         } input_triggers;
+
+        /// @brief State of the camera's digital output lines.
         struct camera_properties_output_triggers_s
         {
             struct Trigger exposure, frame_start, trigger_wait;
         } output_triggers;
     };
 
+    /// @brief Stores the metadata about camera properties.
+    /// @details Only used to request metadata from a camera, which expresses
+    ///          capabilities of the camera and acceptable property values.
     struct CameraPropertyMetadata
     {
         struct Property exposure_time_us;
@@ -51,27 +81,27 @@ extern "C"
             struct Property x, y;
         } shape;
 
-        /// bit field: bit i is 1 if SampleType(i) is supported, 0 otherwise
+        /// @brief The bits of this value describe the supported types.
+        /// @details Bit i is 1 if SampleType(i) is supported, 0 otherwise.
         uint64_t supported_pixel_types;
 
         struct CameraPropertyMetadataDigitalLineMetadata
         {
-            /// The number of supported digital IO lines
-            /// Must be less than 8.
+            /// @brief The number of supported digital IO lines. Must be less than 8.
             uint8_t line_count;
 
-            /// name[i] is a short, null terminated string naming line i.
-            /// Support describing up to 8 names for use with triggering.
+            /// @brief Support describing up to 8 names for use with triggering.
+            /// @details name[i] is a short, null terminated string naming line i.
             char names[8][64];
         } digital_lines;
 
         struct CameraPropertiesTriggerMetadata
         {
             struct camera_properties_metadata_trigger_capabilities_s
             {
-                /// Bit x is set if line x can be used as a trigger input.
+                /// @brief Bit i is set if line i can be used as a trigger input.
                 uint8_t input;
-                /// Bit x is set if line x can be used as a trigger output.
+                /// @brief Bit i is set if line i can be used as a trigger output.
                 uint8_t output;
             } acquisition_start, exposure, frame_start;
         } triggers;