doc_tex -> doxygen of the Kernel_d documentation

Kernel_23/doc/Kernel_23/CGAL/intersections.h

@@ -168,6 +168,23 @@ bool do_intersect(Type1<SphericalKernel> obj1, Type2<SphericalKernel> obj2, Type
 /// @}
 
 
+
+
+/*!
+\addtogroup intersection
+
+The macro `CGAL_INTERSECTION_VERSION` can be used to configure
+which version of the `intersection()` function should be used and
+enables the corresponding APIs in other \cgal packages. It should be
+defined before any \cgal header is included.
+
+- `CGAL_INTERSECTION_VERSION == 1` `intersection()` uses `Object`
+- `CGAL_INTERSECTION_VERSION == 2` `intersection()` uses `boost::optional< boost::variant< T... > >`
+
+*/
+
+#define CGAL_INTERSECTION_VERSION
+
 /*!
 \addtogroup intersection
 

Kernel_d/doc/Kernel_d/CGAL/intersections_d.h

@@ -26,21 +26,19 @@ bool do_intersect(Type1<R> obj1, Type2<R> obj2);
 /*!
 \ingroup PkgKernelDFunctions
 
-returns the intersection result of \f$ f1\f$ and \f$ f2\f$ by means of
+returns the intersection result of \f$ f1\f$ and \f$ f2\f$.
-the polymorphic wrapper type `Object`. The returned object can be
-tested for the intersection result and assigned by means of the
-`object_cast` function. 
-
 \pre The objects are of the same dimension.
 
-The possible value for types `Type1` and `Type2` and 
+The same functionality is also available through the functor `Kernel::Intersect_d`.
-the possible return values wrapped in `Object` are the following: 
+ 
+The possible value for types `Type1` and `Type2` and
+the value for `T...` in `boost::optional< boost::variant< T... > >` are the following:
 
 <DIV ALIGN="CENTER"> 
 <TABLE CELLPADDING=3 BORDER="1"> 
 <TR> <TH> Type1 </TH> 
 <TH> Type2 </TH> 
-<TH> Return Type </TH> 
+<TH> `T...` </TH> 
 </TR> 
 <TR> 
 <TD VALIGN="CENTER" > Line_d </TD> 
@@ -126,21 +124,35 @@ The following example demonstrates the most common use of
 \code
 #include <CGAL/intersections_d.h> 
 
+ 
+template<typename R>
+struct Intersection_visitor {
+  typedef result_type void;
+  void operator()(const Point_d<R>& p) const { /* handle point */ }
+  void operator()(const Segment_d<R>& s) const { /* handle segment */ }
+};
+
 template <class R> 
 void foo(Segment_d<R> seg, Line_d<R> lin) 
 { 
-  Object result = intersection(seg, lin); 
+  // with C++11 support
-  if (const Point_d<R> *ipnt = object_cast<Point_d<R> >(&result) ) { 
+  // auto result = intersection(seg, lin);
-  // handle the point intersection case with *ipnt. 
+
-  } else if (const Segment_d<R> *iseg = object_cast<Segment_d<R> >(&result) ) { 
+  // without C++11 support
-  // handle the segment intersection case with *iseg. 
+  typename boost::result_of<R::Intersect_d(Segment_d<R>, Line_d<R>)>::type
-  } else { 
+    result = intersection(seg, lin);
-  // handle the no intersection case. 
+
-  } 
+  if(result) { boost::apply_visitor(Intersection_visitor<R>(), *result); } 
+  else { // no intersection  
+  }
 } 
 \endcode
 
-\sa `do_intersect`, \sa `Kernel_d::Intersect_d` 
+\sa `do_intersect`
+\sa `Kernel_d::Intersect_d` 
+\sa <a HREF="http://www.boost.org/doc/libs/release/libs/optional/index.html"> `boost::optional`</a>
+\sa <a HREF="http://www.boost.org/doc/html/variant.html">`boost::variant`</a>
+\sa <a HREF="http://www.boost.org/libs/utility/utility.htm#result_of">`boost::result_of`</a>
 
 */
 Object intersection(Type1<R> f1, Type2<R> f2);

Kernel_d/doc/Kernel_d/Concepts/Kernel--Intersect_d.h

@@ -15,14 +15,15 @@ public:
 
 /*! 
 returns the result of the intersection of \f$ p\f$ and \f$ q\f$ in form of a 
-polymorphic object. `Kernel_object` may be any of 
+polymorphic object. `Type1` and `Type2` may be any of 
 `Kernel_d::Segment_d`, `Kernel_d::Ray_d`, `Kernel_d::Line_d`, 
 `Kernel_d::Hyperplane_d`. 
 
 \pre `p` and `q` have the same dimension. 
 */ 
-template <class Kernel_object> Object 
+  template <class Type1, class Type2>
-operator()(const Kernel_object& p, const Kernel_object& q); 
+boost::result_of<Kernel::Intersect_d(Type1, Type2)>::type
+operator()(const Type1& p, const Type2& q); 
 
 /// @}
 

Kernel_d/doc/Kernel_d/Kernel_d.txt

@@ -429,24 +429,22 @@ always cheaper.
 defined, especially integer types and rationals.
 </UL>
 
-\subsection Kernel_dIntersectionandPolymorphicReturn Intersection and Polymorphic Return Values
+\subsection Kernel_dIntersections Intersections
 
 Intersections on kernel objects currently cover only those objects
 that are part of flats (`Segment_d<R>`, `Ray_d<R>`,
 `Line_c<R>`, and `Hyperplane_d<R>`). For any pair of objects
 \f$ o1\f$, \f$ o2\f$ of these types the operation `intersection(o1,o2)`
-returns a polymorphic object that wraps the result of the intersection
+returns a `boost::optional< boost::variant< T... > >`
-operation.
+where `T...` is a list of all possible resulting geometric objects.
+
+The exact result type of an intersection can be determined by using
+`boost::result_of<Kernel::Intersect_d(Type1, Type2)>::type`
+`where `Type1` and `Type2` are the types of the objects
+used in the intersection query. See
+<A HREF="http://www.boost.org/libs/utility/utility.htm#result_of">`boost::result_of`</A>
+for more information about this mechanism.
 
-The class `Object` provides the polymorphic abstraction. An
-object `obj` of type `Object` can represent an arbitrary
-class. The only operations it provides is to make copies and
-assignments, so that you can put them in lists or arrays. Note that
-`Object` is NOT a common base class for the elementary classes.
-Therefore, there is no automatic conversion from these classes to
-`Object` Rather this is done with the global function
-`make_object()`. This encapsulation mechanism requires the use of
-`object_cast` to unwrap the encapsulated class.
 
 \subsubsection Kernel_dExample Example
 
@@ -455,17 +453,25 @@ the intersection computation, as there are
 possibly different return values.
 
 \code{.cpp}
-typedef Point_d< Cartesian_d<double> > Point;
+typedef Cartesian_d<double> K;
-typedef Segment_d< Cartesian_d<double> > Segment;
+typedef Point_d<K> Point;
+typedef Segment_d<K> Segment;
 Segment s1, s2;
 std::cin >> s1 >> s2;
-Object obj = intersection(s1, s2);
+
-if (const Point *p = object_cast<Point>(&obj) ) {
+boost::result_of<K::Intersect_d(Segment, Segment)>::type
-// do something with *p
+  v = intersection(s1, s2);
-} else if (const Segment *s = object_cast<Segment>(&obj) ) {
+if(v) {
-// do something with *s
+  // not empty
+  if (const Point *p = boost::get<Point>(&*v) ) {
+    // do something with *p
+  } else {
+    const Segment *s = boost::get<Segment>(&*v) ) {
+    // do something with *s
+  }
+} else {
+  // empty intersection
 }
-// there was no intersection 
 \endcode
 
 \subsection Kernel_dConstructivePredicates Constructive Predicates