Added and updated documentation of correct, transform, distance, comparable_distance

[SVN r71152]

include/boost/geometry/algorithms/comparable_distance.hpp

@@ -25,13 +25,18 @@ namespace boost { namespace geometry
 /*!
 \brief \brief_calc2{comparable distance measurement}
 \ingroup distance
-\details The default strategy is used, belonging to the corresponding coordinate system of the geometries
-    and the comparable strategy is used
+\details The free function comparable_distance does not necessarily calculate the distance,
+    but it calculates a distance measure such that two distances are comparable to each other.
+    For example: for the Cartesian coordinate system, Pythagoras is used but the square root
+    is not taken, which makes it faster and the results of two point pairs can still be 
+    compared to each other.
 \tparam Geometry1 first geometry type
 \tparam Geometry2 second geometry type
 \param geometry1 \param_geometry
 \param geometry2 \param_geometry
 \return \return_calc{comparable distance}
+
+\qbk{[include reference/algorithms/comparable_distance.qbk]}
  */
 template <typename Geometry1, typename Geometry2>
 inline typename default_distance_result<Geometry1, Geometry2>::type comparable_distance(

include/boost/geometry/algorithms/correct.hpp

@@ -93,7 +93,7 @@ struct correct_box
 
     static inline void apply(Box& box)
     {
-        // Currently only for Cartesian coordinates 
+        // Currently only for Cartesian coordinates
         // (or spherical without crossing dateline)
         // Future version: adapt using strategies
         correct_box_loop
@@ -245,10 +245,15 @@ struct correct<polygon_tag, Polygon>
 
 /*!
 \brief Corrects a geometry
-\details Corrects a geometry
+\details Corrects a geometry: all rings which are wrongly oriented with respect
+    to their expected orientation are reversed. To all rings which do not have a
+    closing point and are typed as they should have one, the first point is
+    appended. Also boxes can be corrected.
 \ingroup correct
 \tparam Geometry \tparam_geometry
-\param geometry \param_geometry
+\param geometry \param_geometry which will be corrected if necessary
+
+\qbk{[include reference/algorithms/correct.qbk]}
 */
 template <typename Geometry>
 inline void correct(Geometry& geometry)

include/boost/geometry/algorithms/distance.hpp

@@ -523,12 +523,14 @@ inline typename strategy::distance::services::return_type<Strategy>::type distan
 /*!
 \brief \brief_calc2{distance}
 \ingroup distance
-\details The default strategy is used, belonging to the corresponding coordinate system of the geometries
+\details The default strategy is used, corresponding to the coordinate system of the geometries
 \tparam Geometry1 \tparam_geometry
 \tparam Geometry2 \tparam_geometry
 \param geometry1 \param_geometry
 \param geometry2 \param_geometry
 \return \return_calc{distance}
+
+\qbk{[include reference/algorithms/distance.qbk]}
  */
 template <typename Geometry1, typename Geometry2>
 inline typename default_distance_result<Geometry1, Geometry2>::type distance(

include/boost/geometry/algorithms/transform.hpp

@@ -289,14 +289,19 @@ struct transform<segment_tag, segment_tag, Segment1, Segment2, Strategy>
 
 
 /*!
-\brief Transforms from one geometry to another geometry using a strategy
+\brief Transforms from one geometry to another geometry  \brief_strategy
 \ingroup transform
 \tparam Geometry1 \tparam_geometry
 \tparam Geometry2 \tparam_geometry
 \tparam Strategy strategy
 \param geometry1 \param_geometry
 \param geometry2 \param_geometry
-\param strategy the strategy to be used for transformation
+\param strategy The strategy to be used for transformation
+\return True if the transformation could be done
+
+\qbk{distinguish,with strategy}
+
+\qbk{[include reference/algorithms/transform_with_strategy.qbk]}
  */
 template <typename Geometry1, typename Geometry2, typename Strategy>
 inline bool transform(Geometry1 const& geometry1, Geometry2& geometry2,
@@ -325,7 +330,9 @@ inline bool transform(Geometry1 const& geometry1, Geometry2& geometry2,
 \tparam Geometry2 \tparam_geometry
 \param geometry1 \param_geometry
 \param geometry2 \param_geometry
-\return true if the transformation could be done
+\return True if the transformation could be done
+
+\qbk{[include reference/algorithms/transform.qbk]}
  */
 template <typename Geometry1, typename Geometry2>
 inline bool transform(Geometry1 const& geometry1, Geometry2& geometry2)

include/boost/geometry/geometry.hpp

@@ -42,6 +42,7 @@
 #include <boost/geometry/algorithms/clear.hpp>
 #include <boost/geometry/algorithms/convex_hull.hpp>
 #include <boost/geometry/algorithms/correct.hpp>
+#include <boost/geometry/algorithms/comparable_distance.hpp>
 #include <boost/geometry/algorithms/difference.hpp>
 #include <boost/geometry/algorithms/distance.hpp>
 #include <boost/geometry/algorithms/envelope.hpp>