Merge pull request #84 from LucileRemigy/refactoring

Organize documentation

include/hpp/fcl/BV/AABB.h

@@ -46,6 +46,10 @@ namespace hpp
 namespace fcl
 {
   class CollisionRequest;
+/// @defgroup Bounding_Volume 
+/// regroup class of differents types of bounding volume.
+/// @{
+
 /// @brief A class describing the AABB collision structure, which is a box in 3D space determined by two diagonal points
 class AABB
 {

include/hpp/fcl/BV/BV.h

@@ -47,7 +47,7 @@
 #include <hpp/fcl/BV/kIOS.h>
 #include <hpp/fcl/math/transform.h>
 
-/** \brief Main namespace */
+/** @brief Main namespace */
 namespace hpp
 {
 namespace fcl

include/hpp/fcl/BV/BV_node.h

@@ -49,6 +49,10 @@ namespace hpp
 namespace fcl
 {
 
+/// @defgroup Construction_Of_BVH 
+/// regroup class which are used to build BVH (Bounding Volume Hierarchy)
+/// @{
+
 /// @brief BVNodeBase encodes the tree structure for BVH
 struct BVNodeBase
 {

include/hpp/fcl/BV/OBB.h

@@ -46,6 +46,9 @@ namespace fcl
 {
   class CollisionRequest;
 
+/// @addtogroup Bounding_Volume
+/// @{
+
 /// @brief Oriented bounding box class
 class OBB
 {
@@ -64,12 +67,12 @@ public:
   bool contain(const Vec3f& p) const;
 
   /// Check collision between two OBB
-  /// \return true if collision happens. 
+  /// @return true if collision happens. 
   bool overlap(const OBB& other) const;
 
   /// Check collision between two OBB
-  /// \return true if collision happens. 
-  /// \retval sqrDistLowerBound squared lower bound on distance between boxes if
+  /// @return true if collision happens. 
+  /// @retval sqrDistLowerBound squared lower bound on distance between boxes if
   ///         they do not overlap.
   bool overlap(const OBB& other, const CollisionRequest& request,
                FCL_REAL& sqrDistLowerBound) const;
@@ -141,9 +144,9 @@ bool overlap(const Matrix3f& R0, const Vec3f& T0, const OBB& b1,
 
 
 /// Check collision between two boxes
-/// \param B, T orientation and position of first box,
-/// \param a half dimensions of first box,
-/// \param b half dimensions of second box.
+/// @param B, T orientation and position of first box,
+/// @param a half dimensions of first box,
+/// @param b half dimensions of second box.
 /// The second box is in identity configuration.
 bool obbDisjoint(const Matrix3f& B, const Vec3f& T, const Vec3f& a, const Vec3f& b);
 }

include/hpp/fcl/BV/OBBRSS.h

@@ -48,6 +48,9 @@ namespace fcl
 {
   class CollisionRequest;
 
+/// @addtogroup Bounding_Volume
+/// @{
+
 /// @brief Class merging the OBB and RSS, can handle collision and distance simultaneously
 class OBBRSS
 {
@@ -72,7 +75,7 @@ public:
   }
 
   /// Check collision between two OBBRSS
-  /// \retval sqrDistLowerBound squared lower bound on distance between
+  /// @retval sqrDistLowerBound squared lower bound on distance between
   ///         objects if they do not overlap.
   bool overlap(const OBBRSS& other, const CollisionRequest& request,
                FCL_REAL& sqrDistLowerBound) const
@@ -154,9 +157,9 @@ inline bool overlap(const Matrix3f& R0, const Vec3f& T0, const OBBRSS& b1, const
 }
 
 /// Check collision between two OBBRSS
-/// \param  b1 first OBBRSS in configuration (R0, T0)
-/// \param  b2 second OBBRSS in identity position
-/// \retval squared lower bound on the distance if OBBRSS do not overlap.
+/// @param  b1 first OBBRSS in configuration (R0, T0)
+/// @param  b2 second OBBRSS in identity position
+/// @retval squared lower bound on the distance if OBBRSS do not overlap.
 inline bool overlap(const Matrix3f& R0, const Vec3f& T0, const OBBRSS& b1,
                     const OBBRSS& b2, const CollisionRequest& request,
 	            FCL_REAL& sqrDistLowerBound)

include/hpp/fcl/BV/RSS.h

@@ -48,6 +48,9 @@ namespace fcl
 {
 
   class CollisionRequest;
+/// @addtogroup Bounding_Volume
+/// @{
+
 /// @brief A class for rectangle sphere-swept bounding volume
 class RSS
 {

include/hpp/fcl/BV/kDOP.h

@@ -48,6 +48,9 @@ namespace fcl
 
   class CollisionRequest;
 
+  /// @addtogroup Bounding_Volume
+  /// @{
+
 /// @brief KDOP class describes the KDOP collision structures. K is set as the template parameter, which should be 16, 18, or 24
 ///  The KDOP structure is defined by some pairs of parallel planes defined by some axes. 
 /// For K = 16, the planes are 6 AABB planes and 10 diagonal planes that cut off some space of the edges:

include/hpp/fcl/BV/kIOS.h

@@ -46,7 +46,10 @@ namespace hpp
 namespace fcl
 {
   class CollisionRequest;
- 
+
+/// @addtogroup Bounding_Volume
+/// @{
+
 /// @brief A class describing the kIOS collision structure, which is a set of spheres.
 class kIOS
 {

include/hpp/fcl/BVH/BVH_model.h

@@ -50,6 +50,9 @@ namespace hpp
 namespace fcl
 {
 
+/// @addtogroup Construction_Of_BVH
+/// @{
+
 class ConvexBase;
 
 template <typename BV> class BVFitter;
@@ -338,7 +341,7 @@ private:
   /// @brief Recursive kernel for bottomup refitting 
   int recursiveRefitTree_bottomup(int bv_id);
 
-  /// @recursively compute each bv's transform related to its parent. For default BV, only the translation works. 
+  /// @ recursively compute each bv's transform related to its parent. For default BV, only the translation works. 
   /// For oriented BV (OBB, RSS, OBBRSS), special implementation is provided.
   void makeParentRelativeRecurse(int bv_id, Matrix3f& parent_axes, const Vec3f& parent_c)
   {
@@ -353,6 +356,7 @@ private:
   }
 };
 
+/// @}
 
 template<>
 void BVHModel<OBB>::makeParentRelativeRecurse(int bv_id, Matrix3f& parent_axes, const Vec3f& parent_c);

include/hpp/fcl/collision_data.h

@@ -215,7 +215,7 @@ public:
   Vec3f cached_gjk_guess;
 
   /// Lower bound on distance between objects if they are disjoint
-  /// \note computed only on request.
+  /// @note computed only on request.
   FCL_REAL distance_lower_bound;
 
 public:

include/hpp/fcl/collision_object.h

@@ -56,6 +56,9 @@ enum OBJECT_TYPE {OT_UNKNOWN, OT_BVH, OT_GEOM, OT_OCTREE, OT_COUNT};
 enum NODE_TYPE {BV_UNKNOWN, BV_AABB, BV_OBB, BV_RSS, BV_kIOS, BV_OBBRSS, BV_KDOP16, BV_KDOP18, BV_KDOP24,
                 GEOM_BOX, GEOM_SPHERE, GEOM_CAPSULE, GEOM_CONE, GEOM_CYLINDER, GEOM_CONVEX, GEOM_PLANE, GEOM_HALFSPACE, GEOM_TRIANGLE, GEOM_OCTREE, NODE_COUNT};
 
+/// @addtogroup Construction_Of_BVH
+/// @{
+
 /// @brief The geometry for the object for collision or distance computation
 class CollisionGeometry
 {

include/hpp/fcl/distance.h

@@ -33,7 +33,7 @@
  *  POSSIBILITY OF SUCH DAMAGE.
  */
 
-/** \author Jia Pan */
+/** @author Jia Pan */
 
 #ifndef HPP_FCL_DISTANCE_H
 #define HPP_FCL_DISTANCE_H

include/hpp/fcl/mesh_loader/loader.h

@@ -53,7 +53,7 @@ namespace fcl {
     public:
       virtual ~MeshLoader() {}
 
-       /// \param bvType ignored
+      /// \param bvType ignored
       /// \deprecated Use MeshLoader::load(const std::string&, const Vec3f&)
       BVHModelPtr_t load (const std::string& filename,
           const Vec3f& scale,

include/hpp/fcl/narrowphase/gjk.h

@@ -54,21 +54,21 @@ Vec3f getSupport(const ShapeBase* shape, const Vec3f& dir, bool dirIsNormalized)
 
 /// @brief Minkowski difference class of two shapes
 ///
-/// \todo template this by the two shapes. The triangle / triangle case can be
+/// @todo template this by the two shapes. The triangle / triangle case can be
 ///       easily optimized computing once the triangle shapes[1] into frame0
 ///
-/// \note The Minkowski difference is expressed in the frame of the first shape.
+/// @note The Minkowski difference is expressed in the frame of the first shape.
 struct MinkowskiDiff
 {
   /// @brief points to two shapes
   const ShapeBase* shapes[2];
 
   /// @brief rotation from shape1 to shape0
-  /// such that \f$ p_in_0 = oR1 * p_in_1 + ot1 \f$.
+  /// such that @f$ p_in_0 = oR1 * p_in_1 + ot1 @f$.
   Matrix3f oR1;
 
   /// @brief translation from shape1 to shape0
-  /// such that \f$ p_in_0 = oR1 * p_in_1 + ot1 \f$.
+  /// such that @f$ p_in_0 = oR1 * p_in_1 + ot1 @f$.
   Vec3f ot1;
 
   typedef void (*GetSupportFunction) (const MinkowskiDiff& minkowskiDiff,
@@ -107,7 +107,7 @@ struct MinkowskiDiff
 
 /// @brief class for GJK algorithm
 ///
-/// \note The computations are performed in the frame of the first shape.
+/// @note The computations are performed in the frame of the first shape.
 struct GJK
 {
   struct SimplexV
@@ -166,7 +166,7 @@ struct GJK
   }
 
   /// Get the closest points on each object.
-  /// \return true on success
+  /// @return true on success
   static bool getClosestPoints (const Simplex& simplex, Vec3f& w0, Vec3f& w1);
 
   /// @brief get the guess from current simplex
@@ -174,7 +174,7 @@ struct GJK
 
   /// @brief Distance threshold for early break.
   /// GJK stops when it proved the distance is more than this threshold.
-  /// \note The closest points will be erroneous in this case.
+  /// @note The closest points will be erroneous in this case.
   ///       If you want the closest points, set this to infinity (the default).
   void setDistanceEarlyBreak (const FCL_REAL& dup)
   {

include/hpp/fcl/narrowphase/narrowphase.h

@@ -94,7 +94,7 @@ namespace fcl
     }
 
     //// @brief intersection checking between one shape and a triangle with transformation
-    /// \return true if the shape are colliding.
+    /// @return true if the shape are colliding.
     template<typename S>
     bool shapeTriangleInteraction
     (const S& s, const Transform3f& tf1, const Vec3f& P1, const Vec3f& P2,

include/hpp/fcl/profile.h

@@ -115,7 +115,7 @@ public:
   class ScopedBlock
   {
   public:
-    /// @brief Start counting time for the block named \e name of the profiler \e prof
+    /// @brief Start counting time for the block named @e name of the profiler @e prof
     ScopedBlock(const std::string &name, Profiler &prof = Profiler::Instance()) : name_(name), prof_(prof)
     {
       prof_.begin(name);
@@ -138,7 +138,7 @@ public:
   {
   public:
 
-    /// @brief Take as argument the profiler instance to operate on (\e prof)
+    /// @brief Take as argument the profiler instance to operate on (@e prof)
     ScopedStart(Profiler &prof = Profiler::Instance()) : prof_(prof), wasRunning_(prof_.running())
     {
       if (!wasRunning_)

include/hpp/fcl/shape/geometric_shapes.h

@@ -62,6 +62,10 @@ public:
   OBJECT_TYPE getObjectType() const { return OT_GEOM; }
 };
 
+/// @defgroup Geometric_Shapes
+/// regroup class of differents types of geometric shapes.
+/// @{
+
 /// @brief Triangle stores the points instead of only indices of points
 class TriangleP : public ShapeBase
 {
@@ -281,6 +285,7 @@ public:
 class ConvexBase : public ShapeBase
 {
 public:
+
   virtual ~ConvexBase();
 
   /// @brief Compute AABB 

src/BVH/BVH_utility.cpp

@@ -218,7 +218,7 @@ void getCovariance(Vec3f* ps, Vec3f* ps2, Triangle* ts, unsigned int* indices, i
 }
 
 
-/** \brief Compute the RSS bounding volume parameters: radius, rectangle size and the origin.
+/** @brief Compute the RSS bounding volume parameters: radius, rectangle size and the origin.
  * The bounding volume axes are known.
  */
 void getRadiusAndOriginAndRectangleSize(Vec3f* ps, Vec3f* ps2, Triangle* ts, unsigned int* indices, int n, const Matrix3f& axes, Vec3f& origin, FCL_REAL l[2], FCL_REAL& r)
@@ -499,7 +499,7 @@ void getRadiusAndOriginAndRectangleSize(Vec3f* ps, Vec3f* ps2, Triangle* ts, uns
 }
 
 
-/** \brief Compute the bounding volume extent and center for a set or subset of points.
+/** @brief Compute the bounding volume extent and center for a set or subset of points.
  * The bounding volume axes are known.
  */
 static inline void getExtentAndCenter_pointcloud(Vec3f* ps, Vec3f* ps2, unsigned int* indices, int n, Matrix3f& axes, Vec3f& center, Vec3f& extent)
@@ -544,7 +544,7 @@ static inline void getExtentAndCenter_pointcloud(Vec3f* ps, Vec3f* ps2, unsigned
 }
 
 
-/** \brief Compute the bounding volume extent and center for a set or subset of points.
+/** @brief Compute the bounding volume extent and center for a set or subset of points.
  * The bounding volume axes are known.
  */
 static inline void getExtentAndCenter_mesh(Vec3f* ps, Vec3f* ps2, Triangle* ts, unsigned int* indices, int n, Matrix3f& axes, Vec3f& center, Vec3f& extent)

src/collision_node.h

@@ -35,15 +35,14 @@
 
 /** \author Jia Pan */
 
-
 #ifndef HPP_FCL_COLLISION_NODE_H
 #define HPP_FCL_COLLISION_NODE_H
 
+/// @cond INTERNAL
+
+#include <hpp/fcl/BVH/BVH_front.h>
 #include "traversal/traversal_node_base.h"
 #include "traversal/traversal_node_bvhs.h"
-#include <hpp/fcl/BVH/BVH_front.h>
-
-
 
 /// @brief collision and distance function on traversal nodes. these functions provide a higher level abstraction for collision functions provided in collision_func_matrix
 namespace hpp
@@ -54,16 +53,14 @@ namespace fcl
 
 /// collision on collision traversal node
 /// 
-/// \param node node containing both objects to test,
-/// \retval squared lower bound to the distance between the objects if they
+/// @param node node containing both objects to test,
+/// @retval squared lower bound to the distance between the objects if they
 ///         do not collide.
-/// \param front_list list of nodes visited by the query, can be used to
+/// @param front_list list of nodes visited by the query, can be used to
 ///        accelerate computation
-  void collide(CollisionTraversalNodeBase* node,
-               const CollisionRequest& request,
-               CollisionResult& result,
-	       BVHFrontList* front_list = NULL,
-               bool recursive = true);
+void collide(CollisionTraversalNodeBase* node, const CollisionRequest& request,
+             CollisionResult& result, BVHFrontList* front_list = NULL,
+             bool recursive = true);
 
 /// @brief distance computation on distance traversal node; can use front list to accelerate
 void distance(DistanceTraversalNodeBase* node, BVHFrontList* front_list = NULL, int qsize = 2);
@@ -71,4 +68,6 @@ void distance(DistanceTraversalNodeBase* node, BVHFrontList* front_list = NULL,
 
 } // namespace hpp
 
+/// @endcond
+
 #endif

src/distance_func_matrix.h

@@ -34,12 +34,18 @@
 
 /** \author Florent Lamiraux */
 
+#ifndef HPP_FCL_DISTANCE_FUNC_MATRIX_H
+#define HPP_FCL_DISTANCE_FUNC_MATRIX_H
+
+/// @cond INTERNAL
+
 #include <hpp/fcl/collision_data.h>
 #include <hpp/fcl/narrowphase/narrowphase.h>
 
 namespace hpp
 {
-namespace fcl {
+namespace fcl
+{
   template<typename T_SH1, typename T_SH2>
     FCL_REAL ShapeShapeDistance
     (const CollisionGeometry* o1, const Transform3f& tf1,
@@ -56,3 +62,7 @@ namespace fcl {
 }
 
 } // namespace hpp
+
+/// @endcond
+
+#endif
\ No newline at end of file