From: Daniel Arndt Date: Sun, 1 Jul 2018 23:44:33 +0000 (+0200) Subject: Fix kdtree documentation and reflow comments manually X-Git-Tag: v9.1.0-rc1~953^2 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F6871%2Fhead;p=dealii.git Fix kdtree documentation and reflow comments manually --- diff --git a/include/deal.II/numerics/kdtree.h b/include/deal.II/numerics/kdtree.h index 243f497b89..5cdb6b8ac9 100644 --- a/include/deal.II/numerics/kdtree.h +++ b/include/deal.II/numerics/kdtree.h @@ -37,9 +37,8 @@ DEAL_II_NAMESPACE_OPEN * order $\log(n)$, where $n$ is the number of points stored in this class. * * The wrapper provides methods that give access to some of the functionalities - * of the nanoflann library, like searching the $p$ nearest neighbors of - * a given point, or - * searching the points that fall within a radius of a target point. + * of the nanoflann library, like searching the $p$ nearest neighbors of a given + * point, or searching the points that fall within a radius of a target point. * * > From wikipedia (https://en.wikipedia.org/wiki/K-d_tree): * > @@ -47,15 +46,15 @@ DEAL_II_NAMESPACE_OPEN * > Every non-leaf node can be thought of as implicitly generating a splitting * > hyperplane that divides the space into two parts, known as half-spaces. * > Points to the left of this hyperplane are represented by the left subtree - * of > that node and points right of the hyperplane are represented by the - * right > subtree. The hyperplane direction is chosen in the following way: - * every node > in the tree is associated with one of the $k$-dimensions, with - * the hyperplane > perpendicular to that dimension's axis. So, for example, if - * for a particular > split the "x" axis is chosen, all points in the subtree - * with a smaller "x" > value than the node will appear in the left subtree and - * all points with > larger "x" value will be in the right subtree. In such a - * case, the > hyperplane would be set by the $x$-value of the point, and its - * normal would be > the unit $x$-axis. + * > of that node and points right of the hyperplane are represented by the + * > right subtree. The hyperplane direction is chosen in the following way: + * > every node in the tree is associated with one of the $k$-dimensions, with + * > the hyperplane perpendicular to that dimension's axis. So, for example, if + * > for a particular split the "x" axis is chosen, all points in the subtree + * > with a smaller "x" value than the node will appear in the left subtree and + * > all points with larger "x" value will be in the right subtree. In such a + * > case, the hyperplane would be set by the $x$-value of the point, and its + * > normal would be the unit $x$-axis. * * @author Luca Heltai, 2017. */ @@ -69,25 +68,22 @@ public: * @param[in] max_leaf_size A number denoting how many points per leaf * are used in the kdtree algorithm. * - * @param[in] pts A vector of points that are to be represented by - * the current object. If no points are passed to this constructor - * (or if the default value of the argument is used), then you have - * to pass them later to this object by calling the set_points() - * method. + * @param[in] pts A vector of points that are to be represented by the current + * object. If no points are passed to this constructor (or if the default + * value of the argument is used), then you have to pass them later to this + * object by calling the set_points() method. * - * Access to any of the methods without first passing a reference to - * a vector of points will result in an exception. Only a reference - * to the points is stored, so you should make sure that the life of - * the vector you pass is longer than the life of this class, or - * you will get undefined behaviour. + * Access to any of the methods without first passing a reference to a vector + * of points will result in an exception. Only a reference to the points is + * stored, so you should make sure that the life of the vector you pass is + * longer than the life of this class, or you will get undefined behaviour. * - * @warning If you change the contents of the vector of points that you - * passed either to the constructor or to set_points(), remember to call - * the set_points() method again. The tree and the index are - * constructed only once when you pass the points (either at - * construction time, or when you call set_points()). If you update - * your points, and do not call set_points() again, then all following results - * will likely be wrong. + * @warning If you change the contents of the vector of points that you passed + * either to the constructor or to set_points(), remember to call the + * set_points() method again. The tree and the index are constructed only once + * when you pass the points (either at construction time, or when you call + * set_points()). If you update your points, and do not call set_points() + * again, then all following results will likely be wrong. */ KDTree(const unsigned int max_leaf_size = 10, const std::vector> &pts = std::vector>()); @@ -95,8 +91,7 @@ public: /** * Adaptor class used internally by nanoflann. This class stores a reference - * to the vector of points, and generates some helper functions for - * nanoflann. + * to the vector of points, and generates some helper functions for nanoflann. */ struct PointCloudAdaptor { @@ -145,9 +140,9 @@ public: /** * Optional bounding-box computation: return false to default to a - * standard bbox computation loop. Return true if the BBOX was + * standard bbox computation loop. Return true if the BBOX was * already computed by the class and returned in "bb" so it can be - * avoided to redo it again. Look at bb.size() to find out the + * avoided to redo it again. Look at bb.size() to find out the * expected dimensionality (e.g. 2 or 3 for point clouds). */ template @@ -167,11 +162,10 @@ public: /** - * Store a reference to the passed points. After you called this - * method, you can call the value() method to compute the minimum - * distance between an evaluation point and the collection of points - * you passed to this method, or the get_points_within_ball() and - * the get_closest_points() methods. + * Store a reference to the passed points. After you called this method, you + * can call the value() method to compute the minimum distance between an + * evaluation point and the collection of points you passed to this method, or + * the get_points_within_ball() and the get_closest_points() methods. * * Notice that the constructor calls this method internally if you * pass it a non-empty vector of points. @@ -208,9 +202,11 @@ public: * * @param[in] target The target point * @param[in] radius The radius of the ball - * @param[in] sorted If @p true, sort the output results in ascending order with respect to distance + * @param[in] sorted If @p true, sort the output results in ascending order + * with respect to distance * - * @return A vector of indices and distances to @p target of the matching points + * @return A vector of indices and distances to @p target + * of the matching points */ std::vector> get_points_within_ball(const Point &target, @@ -218,8 +214,8 @@ public: const bool sorted = false) const; /** - * Fill and return a vector with the indices and distances of the closest @p n_points - * points to the given target point. + * Fill and return a vector with the indices and distances of the closest + * @p n_points points to the given target point. * * @param[in] target The target point * @param[in] n_points The number of requested points