(image_buffer) update docstrings

Author: MatthijsBurgh

ed_sensor_integration/include/ed/kinect/image_buffer.h

@@ -21,7 +21,7 @@ class TransformListener;
 }
 
 /**
- * @brief The ImageBuffer class, provides a buffer to synchronise rgbd images with sensor positions.
+ * @brief The ImageBuffer class provides a buffer to synchronise rgbd images with sensor positions.
  * Images are stored until they are removed from the buffer or until a
  * certain amount of time has passed
  */
@@ -35,28 +35,27 @@ class ImageBuffer
     ~ImageBuffer();
 
     /**
-     * @brief initialize, configure the buffer
-     * @param topic, ros topic on which the rgbd images are published
-     * @param root_frame, root frame to calculate sensor pose relative to (default: map)
-     * @param worker_thread_frequency, frequency at which the worker thread updates the most recent image (default: 20)
+     * @brief Configure the buffer
+     * @param topic ros topic on which the rgbd images are published
+     * @param root_frame root frame to calculate sensor pose relative to (default: map)
+     * @param worker_thread_frequency frequency at which the worker thread updates the most recent image (default: 20)
      */
     void initialize(const std::string& topic, const std::string& root_frame="map", const float worker_thread_frequency=20);
 
     /**
-     * @brief nextImage, Returns the most recent combination of image and transform, provided it is different from the previous time the function was called.
-     *
-     * @param[out] image, rgbd image to write the next image to. Iff a next image is found
-     * @param[out] sensor_pose, will be filled with the sensor pose corresponding to the next image. Iff a next image is found
+     * @brief Returns the most recent combination of image and transform, provided it is different from the previous time the function was called.
+     * @param[out] image rgbd image to write the next image to. Iff a next image is found
+     * @param[out] sensor_pose will be filled with the sensor pose corresponding to the next image. Iff a next image is found
      * @return whether or not a novel image is available
      */
     bool nextImage(rgbd::ImageConstPtr& image, geo::Pose3D& sensor_pose);
 
     /**
-     * @brief waitForRecentImage, Blocks until a new image with transform is found. Returns false if no image or tf could be found within 'timeout_sec' seconds
-     *
-     * @param[out] image, rgbd image to write the next image to. Iff a next image is found
-     * @param[out] sensor_pose, will be filled with the sensor pose corresponding to the next image. Iff a next image is found
-     * @param[in] timeout_sec, maximum duration to block.
+     * @brief Blocks until a new image with transform is found. Returns false if no image or TF could be found within 'timeout_sec' seconds.
+     * But will always give it one try, both to get the image and to get TF.
+     * @param[out] image rgbd image to write the next image to. Iff a next image is found
+     * @param[out] sensor_pose will be filled with the sensor pose corresponding to the next image. Iff a next image is found
+     * @param[in] timeout_sec maximum duration to block.
      * @return whether or not a next image was available within the timeout duration.
      */
     bool waitForRecentImage(rgbd::ImageConstPtr& image, geo::Pose3D& sensor_pose, double timeout_sec);
@@ -77,7 +76,10 @@ class ImageBuffer
     ros::CallbackQueue cb_queue_;
 
     std::pair<rgbd::ImageConstPtr, geo::Pose3D> recent_image_;
-    std::mutex recent_image_mutex_; // For protecting ImageBuffer::recent_image_
+    /**
+     * @brief For protecting ImageBuffer::recent_image_
+     */
+    std::mutex recent_image_mutex_;
     std::unique_ptr<std::thread> worker_thread_ptr_;
     bool shutdown_; // Trigger to kill the worker thread