WIP: Orthtree/quadtree/octree doc

Orthtree/doc/Orthtree/PackageDescription.txt

@@ -36,7 +36,7 @@
 - `SplitCriterion`
 
 \cgalCRPSection{Classes}
-- `CGAL::Orthtree<Traits, PointRange, PointMap>`
-- `CGAL::Octree<GeomTraits, PointRange, PointMap>`
 - `CGAL::Quadtree<GeomTraits, PointRange, PointMap>`
+- `CGAL::Octree<GeomTraits, PointRange, PointMap>`
+- `CGAL::Orthtree<Traits, PointRange, PointMap>`
 */

Orthtree/include/CGAL/Octree.h

@@ -19,10 +19,30 @@
 
 namespace CGAL {
 
+/*!
+ * \ingroup PkgOrthtreeClasses
+ *
+ * \brief alias that specialized the `Orthtree` class to a 3D Octree.
+ *
+ * These two types are exactly equivalent:
+ * - `Octree<GeomTraits, PointRange, PointMap>`
+ * - `Orthtree<Orthtree_traits_3<GeomTraits>, PointRange, PointMap>`.
+ *
+ * \warning this is a not a real class but an alias, please refer to
+ * the documentation of `Orthtree`.
+ *
+ * \tparam GeomTraits is a model of Kernel
+ * \tparam PointRange is a range type that provides random access iterators over the indices of a set of points.
+ * \tparam PointMap is a type that maps items in the range to Point data
+ */
 template <typename GeomTraits, typename PointRange,
           typename PointMap = Identity_property_map
          <typename std::iterator_traits<typename PointRange::iterator>::value_type> >
+#ifdef DOXYGEN_RUNNING
+class Octree;
+#else
 using Octree = Orthtree<Orthtree_traits_3<GeomTraits>, PointRange, PointMap>;
+#endif
 
 } // namespace CGAL
 

Orthtree/include/CGAL/Orthtree.h

@@ -47,14 +47,15 @@ namespace CGAL {
 /*!
  * \ingroup PkgOrthtreeClasses
  *
- * \brief a data structure for efficient computations in 3D space.
+ * \brief a data structure for efficient computations in dD space.
  *
  * \details It builds a hierarchy of nodes which subdivide the space based on a collection of points.
- * Each node represents an axis aligned cubic region of space.
+ * Each node represents an axis aligned hypercubic region of space.
  * A node contains the range of points that are present in the region it defines,
- * and it may contain eight other nodes which further subdivide the region.
+ * and it may contain \f$2^{dim}\f$ other nodes which further subdivide the region.
  *
- * \tparam Point_range is a range type that provides random access iterators over the indices of a set of points.
+ * \tparam Traits is a model of OrthtreeTraits
+ * \tparam PointRange is a range type that provides random access iterators over the indices of a set of points.
  * \tparam PointMap is a type that maps items in the range to Point data
  */
 template<typename Traits, typename PointRange,
@@ -78,7 +79,14 @@ public:
    */
   typedef typename Traits::Point_d Point;
 
+  /*!
+   * \brief Dimension of the tree
+   */
   typedef typename Traits::Dimension Dimension;
+
+  /*!
+   * \brief Degree of the tree (number of children of non-leaf nodes)
+   */
   typedef Dimension_tag<(2 << (Dimension::value-1))> Degree;
 
   /*!
@@ -87,7 +95,7 @@ public:
   typedef typename Traits::FT FT;
 
   /*!
-   * \brief The Sub-tree / Octant type
+   * \brief The Sub-tree / Orthant type
    */
   class Node;
 
@@ -128,7 +136,7 @@ private: // Private types
 
 private: // data members :
 
-  Traits m_traits;
+  Traits m_traits; /* the tree traits */
   PointRange& m_range;              /* input point range */
   PointMap m_point_map;          /* property map: `value_type of InputIterator` -> `Point` (Position) */
 
@@ -138,7 +146,7 @@ private: // data members :
 
   std::vector<FT> m_side_per_depth;      /* side length per node's depth */
 
-  Cartesian_ranges cartesian_range;
+  Cartesian_ranges cartesian_range; /* a helper to easily iterator on coordinates of points */
 
 public:
 
@@ -157,6 +165,7 @@ public:
    * \param point_range random access iterator over the indices of the points
    * \param point_map maps the point indices to their coordinate locations
    * \param enlarge_ratio the degree to which the bounding box should be enlarged
+   * \param traits the traits object
    */
   Orthtree(PointRange& point_range,
          PointMap point_map = PointMap(),
@@ -533,7 +542,7 @@ public:
   /// @{
 
   /*!
-   * \brief compares the topology of a pair of Orthtrees
+   * \brief compares the topology of a pair of orthtrees
    *
    * Trees may be considered equivalent even if they contain different points.
    * Equivalent trees must have the same bounding box and the same node structure.

Orthtree/include/CGAL/Orthtree/Node.h

@@ -29,7 +29,7 @@ namespace CGAL {
 /*!
  * \ingroup PkgOrthtreeClasses
  *
- * \brief represents a single node of the tree. Alternatively referred to as a cell, octant, or subtree
+ * \brief represents a single node of the tree. Alternatively referred to as a cell, orthant, or subtree
  *
  * \details The role of the node isn't fully stable yet
  *
@@ -62,10 +62,9 @@ public:
   /*!
    * \brief set of bits representing this node's relationship to its parent
    *
-   * Equivalent to an array of three booleans,
+   * Equivalent to an array of booleans, where index[0] is whether x
-   * where index[0] is whether x is greater,
+   * is greater, index[1] is whether y is greater, index[2] is whether
-   * index[1] is whether y is greater,
+   * z is greater, and so on for higher dimensions if neede.
-   * and index[2] is whether z is greater.
    * Used to represent a node's relationship to the center of its parent.
    */
   typedef std::bitset<Dimension::value> Index;
@@ -73,8 +72,8 @@ public:
   /*!
    * \brief coordinate location representing this node's relationship with the rest of the tree
    *
-   * Each value (x, y, z) of a location is calculated by doubling the parent's location
+   * Each value (x, y, z, ...) of a location is calculated by doubling
-   * and adding the Index.
+   * the parent's location and adding the Index.
    * \todo Maybe I should add an example?
    */
   typedef std::array<uint32_t, Dimension::value> Int_location;
@@ -336,7 +335,7 @@ public:
 
   /*!
    * \brief retrieve this node's index in relation to its parent
-   * \return the index of this nod3
+   * \return the index of this node
    */
   Index index() const {
 

Orthtree/include/CGAL/Quadtree.h

@@ -19,10 +19,30 @@
 
 namespace CGAL {
 
+/*!
+ * \ingroup PkgOrthtreeClasses
+ *
+ * \brief alias that specialized the `Orthtree` class to a 3D Quadtree.
+ *
+ * These two types are exactly equivalent:
+ * - `Quadtree<GeomTraits, PointRange, PointMap>`
+ * - `Orthtree<Orthtree_traits_2<GeomTraits>, PointRange, PointMap>`.
+ *
+ * \warning this is a not a real class but an alias, please refer to
+ * the documentation of `Orthtree`.
+ *
+ * \tparam GeomTraits is a model of Kernel
+ * \tparam PointRange is a range type that provides random access iterators over the indices of a set of points.
+ * \tparam PointMap is a type that maps items in the range to Point data
+ */
 template <typename GeomTraits, typename PointRange,
           typename PointMap = Identity_property_map
          <typename std::iterator_traits<typename PointRange::iterator>::value_type> >
+#ifdef DOXYGEN_RUNNING
+class Quadtree;
+#else
 using Quadtree = Orthtree<Orthtree_traits_2<GeomTraits>, PointRange, PointMap>;
+#endif
 
 } // namespace CGAL