From db37ec56c2b5127f7dfcee95d0bc2b1359043a3b Mon Sep 17 00:00:00 2001
From: Jane Tournois <jane.tournois@geometryfactory.com>
Date: Tue, 6 Sep 2016 13:05:59 +0200
Subject: [PATCH] add documentation of concept PowerSideOfBoundedPowerSphere_3

---
 .../Concepts/FunctionObjectConcepts.h         | 49 +++++++++++++++----
 1 file changed, 39 insertions(+), 10 deletions(-)

diff --git a/Kernel_23/doc/Kernel_23/Concepts/FunctionObjectConcepts.h b/Kernel_23/doc/Kernel_23/Concepts/FunctionObjectConcepts.h
index 0c9c730a29c..e4788f9c604 100644
--- a/Kernel_23/doc/Kernel_23/Concepts/FunctionObjectConcepts.h
+++ b/Kernel_23/doc/Kernel_23/Concepts/FunctionObjectConcepts.h
@@ -6839,7 +6839,7 @@ public:
   /*!
     constructs the point which is the center of the smallest orthogonal circle to the input weighted points. 
   */ 
-  Kernel::Point_2 operator()(const Kernel::Weighted_point_2& p, const Kernel::Weighted_point_2& q, const Kernel::Weighted_point_3& s);
+  Kernel::Point_2 operator()(const Kernel::Weighted_point_2& p, const Kernel::Weighted_point_2& q, const Kernel::Weighted_point_2& s);
 
 }; /* end Kernel::ConstructWeightedCircumcenter_2
 
@@ -8014,7 +8014,21 @@ public:
   /*!
     returns the sign of the power test of the last weighted point
     with respect to the smallest sphere orthogonal to the others.
-  */ 
+
+    Let \f$ {z(p,q,r,s)}^{(w)}\f$ be the power sphere of the weighted points
+    \f$ (p,q,r,s)\f$. Returns
+    - `ON_BOUNDARY` if `t` is orthogonal to
+    \f$ {z(p,q,r,s)}^{(w)}\f$,
+    - `ON_UNBOUNDED_SIDE` if `t` lies outside the bounded sphere of
+    center \f$ z(p,q,r,s)\f$ and radius \f$ \sqrt{ w_{z(p,q,r,s)}^2 + w_t^2 }\f$
+    (which is equivalent to \f$ \Pi({t}^{(w)},{z(p,q,r,s)}^{(w)} >0\f$)),
+    - `ON_BOUNDED_SIDE` if `t` lies inside this oriented sphere.
+
+    \pre `p, q, r, s` are not coplanar.
+
+    If all the points have a weight equal to 0, then
+    `power_side_of_bounded_power_sphere_3(p,q,r,s,t)` == `side_of_bounded_sphere(p,q,r,s,t)`.
+    */
   CGAL::Bounded_side
   operator()(const Kernel::Weighted_point_3 & p,
              const Kernel::Weighted_point_3 & q,
@@ -8023,25 +8037,40 @@ public:
              const Kernel::Weighted_point_3 & t); 
 
   /*!
-    returns.
-  */ 
+  Analogous to the previous method, for coplanar points,
+  with the power circle \f$ {z(p,q,r)}^{(w)}\f$.
+  \pre `p, q, r` are not collinear.
+
+  If all the points have a weight equal to 0, then
+  `power_side_of_bounded_power_sphere_3(p,q,r,t)` == `side_of_bounded_sphere(p,q,r,t)`.
+  */
   CGAL::Bounded_side
   operator()(const Kernel::Weighted_point_3 & p,
              const Kernel::Weighted_point_3 & q,
              const Kernel::Weighted_point_3 & r,
-             const Kernel::Weighted_point_3 & s); 
+             const Kernel::Weighted_point_3 & t); 
 
   /*!
-    returns.
-  */ 
+  which is the same for collinear points, where \f$ {z(p,q)}^{(w)}\f$ is the
+  power segment of `p` and `q`.
+  \pre `p` and `q` have different bare points.
+
+  If all points have a weight equal to 0, then
+  `power_side_of_bounded_power_sphere_3(p,q,t)` gives the same answer as the kernel predicate
+  `s(p,q).has_on(t)` would give, where `s(p,q)` denotes the
+  segment with endpoints `p` and `q`.
+  */
   CGAL::Bounded_side
   operator()(const Kernel::Weighted_point_3 & p,
              const Kernel::Weighted_point_3 & q,
-             const Kernel::Weighted_point_3 & r);
+             const Kernel::Weighted_point_3 & t);
 
   /*!
-    returns.
-  */ 
+  which is the same for equal points, that is when `p` and `q`
+  have equal coordinates, then it returns the comparison of the weights
+  (`ON_BOUNDED_SIDE` when `q` is heavier than `p`).
+  \pre `p` and `q` have equal bare points.
+  */
   CGAL::Bounded_side
   operator()(const Kernel::Weighted_point_3 & p,
              const Kernel::Weighted_point_3 & q);