Removed documentation of degenerate cases of power_side_of_oriented_* predicates

See Issue https://github.com/CGAL/cgal/issues/2067

Cartesian_kernel/include/CGAL/Cartesian/function_objects.h

@@ -4143,6 +4143,16 @@ namespace CartesianKernelFunctors {
                                                    t.x(), t.y(), t.weight());
     }
 
+    // The methods below are currently undocumented because the definition of
+    // orientation is unclear for 2 and 1 point configurations in a 2D space.
+
+    // One should be (very) careful with the order of vertices when using them,
+    // as swapping points will change the result and one must therefore have a
+    // precise idea of what is the positive orientation in the full space.
+    // For example, these functions are (currently) used safely in the regular
+    // triangulations classes because we always call them on vertices of
+    // triangulation cells, which are always positively oriented.
+
     Oriented_side operator()(const Weighted_point_2& p,
                              const Weighted_point_2& q,
                              const Weighted_point_2& t) const

Homogeneous_kernel/include/CGAL/Homogeneous/function_objects.h

@@ -4450,33 +4450,48 @@ namespace HomogeneousKernelFunctors {
                    t.hx(), t.hy(), t.hz(), t.hw(), t.weight());
       }
 
+    // The methods below are currently undocumented because the definition of
+    // orientation is unclear for 3, 2, and 1 point configurations in a 3D space.
+
+    // One should be (very) careful with the order of vertices when using them,
+    // as swapping points will change the result and one must therefore have a
+    // precise idea of what is the positive orientation in the full space.
+    // For example, these functions are (currently) used safely in the regular
+    // triangulations classes because we always call them on vertices of
+    // triangulation cells, which are always positively oriented.
+
     Oriented_side operator() ( const Weighted_point_3 & p,
                                const Weighted_point_3 & q,
                                const Weighted_point_3 & r,
                                const Weighted_point_3 & s) const
     {
-        return power_side_of_oriented_power_sphereH3(
+      //CGAL_kernel_precondition( coplanar(p, q, r, s) );
+      //CGAL_kernel_precondition( !collinear(p, q, r) );
+      return power_side_of_oriented_power_sphereH3(
                    p.hx(), p.hy(), p.hz(), p.weight(),
                    q.hx(), q.hy(), q.hz(), q.weight(),
                    r.hx(), r.hy(), r.hz(), r.weight(),
                    s.hx(), s.hy(), s.hz(), s.weight());
-      }
+    }
 
     Oriented_side operator() ( const Weighted_point_3 & p,
                                const Weighted_point_3 & q,
                                const Weighted_point_3 & r) const
     {
-        return power_side_of_oriented_power_sphereH3(
+      //CGAL_kernel_precondition( collinear(p, q, r) );
+      //CGAL_kernel_precondition( p.point() != q.point() );
+      return power_side_of_oriented_power_sphereH3(
                    p.x(), p.y(), p.z(), p.weight(),
                    q.x(), q.y(), q.z(), q.weight(),
                    r.x(), r.y(), r.z(), r.weight());
-      }
+    }
 
     Oriented_side operator() ( const Weighted_point_3 & p,
                                const Weighted_point_3 & q) const
-      {
+    {
-        return power_side_of_oriented_power_sphereH3(p.weight(),q.weight());
+      //CGAL_kernel_precondition( p.point() == r.point() );
-      }
+      return power_side_of_oriented_power_sphereH3(p.weight(),q.weight());
+    }
   };
 #endif
 
@@ -4501,6 +4516,16 @@ namespace HomogeneousKernelFunctors {
                           t.hx(), t.hy(), t.hw(), t.weight());
     }
 
+    // The methods below are currently undocumented because the definition of
+    // orientation is unclear for 2 and 1 point configurations in a 2D space.
+
+    // One should be (very) careful with the order of vertices when using them,
+    // as swapping points will change the result and one must therefore have a
+    // precise idea of what is the positive orientation in the full space.
+    // For example, these functions are (currently) used safely in the regular
+    // triangulations classes because we always call them on vertices of
+    // triangulation cells, which are always positively oriented.
+
     Oriented_side operator()(const Weighted_point_2& p,
                              const Weighted_point_2& q,
                              const Weighted_point_2& t) const

Kernel_23/doc/Kernel_23/Concepts/FunctionObjectConcepts.h

@@ -9212,7 +9212,8 @@ public:
   \sa `ComputePowerProduct_2` for the definition of power distance.
   
 */
-  class PowerSideOfOrientedPowerCircle_2 {
+class PowerSideOfOrientedPowerCircle_2
+{
   public:
 
   /// \name Operations
@@ -9230,29 +9231,13 @@ public:
     \pre the bare points corresponding to `p`, `q`, `r` are not collinear.
   */
 
-  Oriented_side operator() ( const Kernel::Weighted_point_2& p,
+  Oriented_side operator()(const Kernel::Weighted_point_2& p,
-                             const Kernel::Weighted_point_2& q,
+                           const Kernel::Weighted_point_2& q,
-                             const Kernel::Weighted_point_2& r,
+                           const Kernel::Weighted_point_2& r,
-                             const Kernel::Weighted_point_2& s);
+                           const Kernel::Weighted_point_2& s);
-
-/*!
-  degenerate power test for collinear points  `p`, `q`, `r`.
-  \pre  `p` and `q` have different bare points.
-*/
-    Oriented_side operator() (  const Kernel::Weighted_point_2& p,
-                                const Kernel::Weighted_point_2& q,
-                                const Kernel::Weighted_point_2& r);
-/*!
-degenerate power test for weighted points
-`p` and `q` whose corresponding bare points are identical. 
-\pre `p` and `q` have equal bare points. 
-*/
-Oriented_side operator() ( const Kernel::Weighted_point_2& p,
-                           const Kernel::Weighted_point_2& q); 
-
   /// @}
 
-  };
+};
 
 /*!
 \ingroup PkgKernel23ConceptsFunctionObjects
@@ -9298,42 +9283,6 @@ public:
                             const Kernel::Weighted_point_3& r,
                             const Kernel::Weighted_point_3& s,
                             const Kernel::Weighted_point_3& t) const;
-
-  /*!
-    Analogous to the previous method, for coplanar points,
-    with the power circle \f$ {z(p,q,r)}^{(w)}\f$.
-
-    \pre `p, q, r, s` are coplanar and `p, q, r` are not collinear.
-  */
-  Oriented_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) const;
-
-  /*!
-    which is the same for collinear points, where \f$ {z(p,q)}^{(w)}\f$ is the
-    power segment of `p` and `q`.
-
-    \pre `p, q, r` are collinear, and `p` and `q` have different bare points.
-
-    If all points have a weight equal to 0, then
-    `power_side_of_oriented_power_sphere_3(p,q,t)` yields an answer consistent with
-    what the kernel predicate `s(p,q).has_on(t)` would give, where `s(p,q)`
-    denotes the segment with endpoints `p` and `q`.
-  */
-  Oriented_side operator()( const Kernel::Weighted_point_3& p,
-                            const Kernel::Weighted_point_3& q,
-                            const Kernel::Weighted_point_3& t) const;
-
-  /*!
-    which is the same for equal points, that is when `p` and `q`
-    have equal coordinates, and returns the comparison of the weights
-    (`ON_POSITIVE_SIDE` when `q` is heavier than `p`).
-
-    \pre `p` and `q` have equal bare points.
-  */
-  Oriented_side operator()( const Kernel::Weighted_point_3& p,
-                            const Kernel::Weighted_point_3& q) const;
   /// @}
 };
 

Kernel_23/include/CGAL/Kernel/function_objects.h

@@ -452,11 +452,23 @@ namespace CommonKernelFunctors {
                                                    t.x(), t.y(), t.z(), t.weight());
     }
 
+    // The methods below are currently undocumented because the definition of
+    // orientation is unclear for 3, 2, and 1 point configurations in a 3D space.
+
+    // One should be (very) careful with the order of vertices when using them,
+    // as swapping points will change the result and one must therefore have a
+    // precise idea of what is the positive orientation in the full space.
+    // For example, these functions are (currently) used safely in the regular
+    // triangulations classes because we always call them on vertices of
+    // triangulation cells, which are always positively oriented.
+
     Oriented_side operator()(const Weighted_point_3 & p,
                              const Weighted_point_3 & q,
                              const Weighted_point_3 & r,
                              const Weighted_point_3 & s) const
     {
+      //CGAL_kernel_precondition( coplanar(p, q, r, s) );
+      //CGAL_kernel_precondition( !collinear(p, q, r) );
       return power_side_of_oriented_power_sphereC3(p.x(), p.y(), p.z(), p.weight(),
                                                    q.x(), q.y(), q.z(), q.weight(),
                                                    r.x(), r.y(), r.z(), r.weight(),
@@ -467,6 +479,8 @@ namespace CommonKernelFunctors {
                              const Weighted_point_3 & q,
                              const Weighted_point_3 & r) const
     {
+      //CGAL_kernel_precondition( collinear(p, q, r) );
+      //CGAL_kernel_precondition( p.point() != q.point() );
       return power_side_of_oriented_power_sphereC3(p.x(), p.y(), p.z(), p.weight(),
                                                    q.x(), q.y(), q.z(), q.weight(),
                                                    r.x(), r.y(), r.z(), r.weight());
@@ -475,6 +489,7 @@ namespace CommonKernelFunctors {
     Oriented_side operator()(const Weighted_point_3 & p,
                              const Weighted_point_3 & q) const
     {
+      //CGAL_kernel_precondition( p.point() == r.point() );
       return power_side_of_oriented_power_sphereC3(p.weight(),q.weight());
     }
   };