Forward declaration, class doc

source/RobotAPI/libraries/core/DebugDrawerTopic.cpp

@@ -2,6 +2,7 @@
 
 #include <VirtualRobot/math/Helpers.h>
 
+#include <ArmarXCore/core/ManagedIceObject.h>
 
 #include "Pose.h"
 

source/RobotAPI/libraries/core/DebugDrawerTopic.h

@@ -2,18 +2,38 @@
 
 #include <Eigen/Geometry>
 
-#include <ArmarXCore/core/ManagedIceObject.h>
-
 #include <RobotAPI/interface/visualization/DebugDrawerInterface.h>
 
 
 namespace armarx
 {
+    // forward declaration
+    class ManagedIceObject;
+
 
+    /**
+     * @brief The DebugDrawerTopic wraps a DebugDrawerInterfacePrx and
+     * provides a more useful interface than the Ice interface.
+     *
+     * The methods by DebugDrawerTopic take "raw" types, such as Eigen or PCL
+     * types, and takes care of conversion to Ice variants or data structures.
+     * In addition, it provides useful overloads for different use cases.
+     *
+     * Methods arguments are ordered from specific to general. That is, common
+     * arguments such as VisuID and color always come last. Less common
+     * parameters (e.g. width of arrow/line), come before them. The first
+     * arguments are those specific to the respective function.
+     * (Added methods should follow this pattern.)
+     *
+     * All methods check whether the internal topic proxy is set, and do
+     * nothing if it is not set. To disable visualization by this classs
+     * completely, just do not set the topic.
+     *
+     */
     class DebugDrawerTopic
     {
     public:
-        
+
         struct VisuID
         {
             /// Construct with empty name and layer name "debug".
@@ -22,25 +42,25 @@ namespace armarx
             VisuID(const std::string& name);
             /// Construct with given layer and name.
             VisuID(const std::string& layer, const std::string& name);
-            
+
             std::string layer = "debug";
             std::string name;
         };
-        
-        
+
+
     public:
 
         /// Construct without topic.
         DebugDrawerTopic();
         /// Construct with given topic.
         DebugDrawerTopic(const DebugDrawerInterfacePrx& topic);
-        
-        
+
+
         /// Set the topic.
         void setTopic(const DebugDrawerInterfacePrx& topic);
         /// Set the topic.
         DebugDrawerInterfacePrx getTopic() const;
-        
+
         /// Call offeringTopic([topicName]) on the given component.
         void offeringTopic(ManagedIceObject& component) const;
         /// Get the topic by calling getTopic([topicName]) on the given component.
@@ -50,27 +70,27 @@ namespace armarx
         /// Set the scale for pose visualization.
         /// This value will be used for all successive calls to drawPose().
         void setPoseScale(float scale);
-        
-        
+
+
         void drawPose(const Eigen::Matrix4f& pose, const VisuID& id);
         void drawPose(const Eigen::Vector3f& pos, const Eigen::Quaternionf& ori, const VisuID& id);
-        
+
         void drawArrow(const Eigen::Vector3f& position, const Eigen::Vector3f& direction, float length,
                        float width, const DrawColor& color, const VisuID& id);
         void drawArrowFromTo(const Eigen::Vector3f& from, const Eigen::Vector3f& to,
                              float width, const DrawColor& color, const VisuID& id);
-        
+
 
 
     private:
 
         static const std::string TOPIC_NAME;
-        
+
         DebugDrawerInterfacePrx topic = nullptr;
-        
+
         float poseScale = 1;
 
-        
+
     };
 
 }