From f2ec162b4f28efda4f1efc5bc5d821b4776dfd9d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mael=20Rouxel-Labb=C3=A9?= Date: Wed, 10 May 2017 12:37:20 +0200 Subject: [PATCH] Clarified some documentation about the usage of Construct_point_23 in TTraits_23 --- .../Concepts/TriangulationTraits_2.h | 15 ++++++++++++--- .../Concepts/TriangulationTraits_3.h | 15 ++++++++++++--- 2 files changed, 24 insertions(+), 6 deletions(-) diff --git a/Triangulation_2/doc/Triangulation_2/Concepts/TriangulationTraits_2.h b/Triangulation_2/doc/Triangulation_2/Concepts/TriangulationTraits_2.h index 2c9a2808ca8..485abbc34af 100644 --- a/Triangulation_2/doc/Triangulation_2/Concepts/TriangulationTraits_2.h +++ b/Triangulation_2/doc/Triangulation_2/Concepts/TriangulationTraits_2.h @@ -51,9 +51,18 @@ Provides: which simply returns p. -\note This constructor is necessary because `Regular_triangulation_2` -inherits `Triangulation_2` and will provide an overload of `Construct_point_2` -that strips the weight from a weighted point. +\note It is advised to return a const reference to `p` to avoid useless copies. + +\note This peculiar requirement is necessary because `CGAL::Triangulation_2` +internally manipulates points with a `Point` type that is not always `Point_2`. +For example, `CGAL::Regular_triangulation_2` inherits `CGAL::Triangulation_2` +with `Point` being a two-dimensional weighted point. Since some predicates and +constructors (such as `Orientation_2`) can only use `Point_2` objects in arguments, +it is necessary to convert objects of type `Point` to objects of type `Point_2` +before calling these functions, using the kernel functor `Construct_point_2`. +In the setting of a basic triangulation, `Point` and `Point_2` are identical and +so `Construct_point_2` is simply the identity. Refinements of this concept will +require more significant overloads to the `Construct_point_2` functor. */ typedef unspecified_type Construct_point_2; diff --git a/Triangulation_3/doc/Triangulation_3/Concepts/TriangulationTraits_3.h b/Triangulation_3/doc/Triangulation_3/Concepts/TriangulationTraits_3.h index ba26a15ab5c..e166aeada83 100644 --- a/Triangulation_3/doc/Triangulation_3/Concepts/TriangulationTraits_3.h +++ b/Triangulation_3/doc/Triangulation_3/Concepts/TriangulationTraits_3.h @@ -50,9 +50,18 @@ A constructor object that must provide the function operator which simply returns p. -\note This constructor is necessary because `Regular_triangulation_3` -inherits `Triangulation_3` and will provide an overload of `Construct_point_3` -that strips the weight from a weighted point. +\note It is advised to return a const reference to `p` to avoid useless copies. + +\note This peculiar requirement is necessary because `CGAL::Triangulation_3` +internally manipulates points with a `Point` type that is not always `Point_3`. +For example, `CGAL::Regular_triangulation_3` inherits `CGAL::Triangulation_3` +with `Point` being a three-dimensional weighted point. Since some predicates and +constructors (such as `Orientation_3`) can only use `Point_3` objects in arguments, +it is necessary to convert objects of type `Point` to objects of type `Point_3` +before calling these functions, using the kernel functor `Construct_point_3`. +In the setting of a basic triangulation, `Point` and `Point_3` are identical and +so `Construct_point_3` is simply the identity. Refinements of this concept will +require more significant overloads to the `Construct_point_3` functor. */ typedef unspecified_type Construct_point_3;