Add initial header comments

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

@@ -14,20 +14,40 @@ extern "C"
         struct Device device;
         enum DeviceState state;
 
+        /// Attempts to set the given properties on the given camera.
+        /// TODO: this will attempt to set as many properties values
+        /// as it can. Some properties (e.g. shape and offset) may be
+        /// coupled - these will be either set atomically or in the
+        /// case that one value is not compatible with others, not
+        /// set at all.
+        /// TODO: should we define a force_set? or define a way to clear
+        /// a settings cache?
+        /// TODO: should we return something to indicate which properties
+        /// were set? Should we define a setget?
         enum DeviceStatusCode (*set)(struct Camera*,
                                      struct CameraProperties* settings);
+        /// Fills out the given properties from the given camera.
         enum DeviceStatusCode (*get)(const struct Camera*,
                                      struct CameraProperties* settings);
+        /// Fills out the given property metadata from the given camera.
+        /// TODO: should each call to the same camera instance fill out the
+        /// the same values? Or should metadata/capabilities depend on
+        /// current property values?
         enum DeviceStatusCode (*get_meta)(const struct Camera*,
                                           struct CameraPropertyMetadata* meta);
+        /// The shape of the next frame that the camera will capture based on its current properties.
         enum DeviceStatusCode (*get_shape)(const struct Camera*,
                                            struct ImageShape* shape);
+        /// Starts acquiring frames.
         enum DeviceStatusCode (*start)(struct Camera*);
+        /// Stops acquiring frames.
+        /// TODO: does this wait/block until any pending frames have been acquired?
         enum DeviceStatusCode (*stop)(struct Camera*);
 
-        // Fire the software trigger if it's enabled.
+        /// Fire the software trigger if it's enabled.
         enum DeviceStatusCode (*execute_trigger)(struct Camera*);
 
+        /// 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,17 +11,35 @@ extern "C"
 {
 #endif
 
+    /// @brief Stores the properties of a camera.
+    /// @details This can be populated with values from a camera.
+    ///          Or can be filled out to request new values a camera should adopt.
     struct CameraProperties
     {
+        /// @brief The 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 The binning factor, which determines how many pixels in each spatial dimension on the sensor are aggregated to form pixels in an image.
+        /// @details 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 The type of each image pixel or sample.
         enum SampleType pixel_type;
+
+        /// @brief The offset of the active image 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 The shape or size of the active region of interest on the sensor.
+        /// 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;
@@ -36,6 +54,9 @@ extern "C"
         } output_triggers;
     };
 
+    /// @brief Stores the metadata about camera properties.
+    /// @details This is 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;
@@ -56,22 +77,21 @@ extern "C"
 
         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 x is set if line x 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 x is set if line x can be used as a trigger output.
                 uint8_t output;
             } acquisition_start, exposure, frame_start;
         } triggers;