update documentation

include/hpp/affordance/affordance-extraction.hh

@@ -25,21 +25,25 @@
 namespace hpp {
   namespace affordance {
 
+		/// Helper struct that saves the global position of the triangle
+		/// vertices of a fcl::Triangle.
 		struct TrianglePoints
     {
       fcl::Vec3f p1, p2, p3;
     };
-		// helper class to save triangle information
+		/// Helper class to save triangle information.
     struct Triangle
     {
       Triangle () {}
-
+			/// Constructor that takes in a TrianglePoints object.
       Triangle (const TrianglePoints& inPoints):
                 points (inPoints)
       {
         TriangleArea (points);
         TriangleNormal (points);
       }
+			/// Computes the area of a triangle.
+			/// \param tri The global position of a triangles vertices
       void TriangleArea(TrianglePoints& tri)
       {
         double a, b, c;
@@ -49,13 +53,19 @@ namespace hpp {
         double s = 0.5 * (a + b + c);
         area = sqrt(s * (s-a) * (s-b) * (s-c));
       }
+			/// Computes the normal vector of a triangle based on the
+			/// global position of its vertices. The normal is subject to convention!
+			/// \param tri The global position of a triangles vertices
       void TriangleNormal(TrianglePoints& tri)
       {
         normal = (tri.p2 - tri.p1).cross(tri.p3 - tri.p1);
         normal.normalize();
       }
+			/// The global position of a triangles vertices.
       TrianglePoints points;
+			/// The area of a triangle.
       double area;
+			/// The normal vector of a triangle.
       fcl::Vec3f normal;
     };
 
@@ -64,6 +74,7 @@ namespace hpp {
 
     /// \addtogroup affordance
     /// \{
+
 		/// Class that saves a reference collision object and indices to
 		/// those of its mesh triangles that form one affordance object.
 		/// This information will later be used to create fcl::collisionObjects
@@ -82,7 +93,11 @@ namespace hpp {
       Affordance (const std::vector<unsigned int>& idxVec,
                   const fcl::CollisionObjectPtr_t& colObj):
                   indices_(idxVec), colObj_(colObj) {}
+			/// Triangle indices that correspond to the triangles of the reference
+			/// collisionObstacle, and form the affordance object.
       std::vector<unsigned int> indices_;
+			/// Reference to the collisionObstacle the surfaces of which are used to
+			/// create the affordance object.
       fcl::CollisionObjectPtr_t colObj_;
     };
 		///	Class containing a vector of vectors of Affordance objects.
@@ -94,6 +109,10 @@ namespace hpp {
       public:
 
       SemanticsData () {}
+			/// Vector of vectors of Affordance objects. The size of the outer
+			/// vector corresponds to the number of affordance types, and that
+			/// of the inner vector to the amount of individual affordance objects
+			/// for each affordance type.
       std::vector<std::vector<AffordancePtr_t> > affordances_;
 			private:
 			SemanticsData(const SemanticsData&); // Prevent copy-construction

include/hpp/affordance/operations.hh

@@ -23,48 +23,85 @@
 
 namespace hpp {
   namespace affordance {
-
+    /// \addtogroup affordance
+    /// \{
+		
+		/// Base class for the data needed to determine affordances of different
+		/// types. For each affordance type, a child class inheriting OperationBase
+		/// will have to be created.
     class OperationBase
     {
       public:
+				/// If an OperationBase object is created without parameters, an
+				/// affordance type called "noAffordance" is created as default,
+				/// with certain default values for its member variables. This
+				/// constructor should not be used..!
         OperationBase (): zWorld_(0,0,1), margin_(0.3), minArea_(0.05), 
                           affordance_("noAffordance") {}
+				/// Constructor that allows for user-defined parameters. Default values are given for
+				/// parameters that are not defined by the user.
+				/// \param margin Margin needed for the evaluation of the requirement function
+				/// \param minArea Minimum area needed for the formation of an affordance object
+				/// \param affordanceName The name of the affordance type
         explicit OperationBase (const double margin = 0.3, const double minArea = 0.05,
                                 const char* affordanceName = "noAffordance"): zWorld_(0,0,1),
                                 margin_(margin), minArea_(minArea), affordance_(affordanceName) {}
+				/// Fully virtual function that will determine whether or not a given 
+				/// triangle normal fullfils the requirement of a child class. If yes,
+				/// the tested triangle forms part of a potential affordance.
+				/// \param normal Normal vector of the tested triangle.
         virtual bool requirement (const fcl::Vec3f& normal) =0;
-
+				/// The orientation of the world z axis. Needed to find potential affordance objects.
         const fcl::Vec3f zWorld_;
+				/// The error margin within which the requirement function must be fullfilled.
         const double margin_;
+				/// The minimum area required for an affordance object. The total area may
+				/// comprise multiple triangles.
         const double minArea_;
+				/// Name of the affordance type for which te requirement exists.
         const char* affordance_;
     }; // class OperationBase
-
+		/// Class that contains the information needed to create affordance
+		/// objects of type Support. Inherits the OperationBase class.
     class SupportOperation : public OperationBase
     {
       public:
-	 explicit SupportOperation (const double margin = 0.3, const double minArea = 0.05, 
+				/// Constructor that takes in user-defined parameters
+				/// \param margin Margin needed for the evaluation of the requirement function
+				/// \param minArea Minimum area needed for the formation of an affordance object
+				/// \param affordanceName The name of the affordance type
+				explicit SupportOperation (const double margin = 0.3, const double minArea = 0.05, 
                                     const char* affordanceName = "Support"):
                                     OperationBase(margin, minArea, affordanceName) {}
-
+				/// The implementation of the requirement function for Support affordances
+				/// overrides the virtual function in class OperationBase.
+				/// \param nromal Normal vector of the tested triangle.
         bool requirement (const fcl::Vec3f& normal) 
       {
         return ((zWorld_ - normal).sqrLength() < margin_);
       }
     }; // class SupportOperation
-   
+    /// Class that contains the information needed to create affordance
+		/// objects of type Lean. Inherits the OperationBase class.
     class LeanOperation : public OperationBase
     {
       public:
-        explicit LeanOperation (const double margin = 0.3, const double minArea = 0.05,
+			/// Constructor that takes in user-defined parameters
+			/// \param margin Margin needed for the evaluation of the requirement function
+			/// \param minArea Minimum area needed for the formation of an affordance object
+			/// \param affordanceName The name of the affordance type
+      explicit LeanOperation (const double margin = 0.3, const double minArea = 0.05,
                                 const char* affordanceName = "Lean"):
                                 OperationBase(margin, minArea, affordanceName) {}
+				/// The implementation of the requirement function for Lean affordances
+				/// overrides the virtual function in class OperationBase.
+				/// \param nromal Normal vector of the tested triangle.
         bool requirement (const fcl::Vec3f& normal) 
         {
           return (fabs (normal.dot(zWorld_)) < margin_);
         }
     }; // class LeanOperation
-   
+		/// \} 
   } // namespace affordance
 } // namespace hpp