Merge branch 'Convex_hull-docfix-philaris'

Fix doxygen conversion errors, clean-up, remove an inlined example
Update an exemple to ease the understanding

Tested in CGAL-4.4-Ic-110

Convex_hull_2/doc/Convex_hull_2/CGAL/ch_graham_andrew.h

@@ -64,9 +64,20 @@ namespace CGAL {
 /*!
 \ingroup PkgConvexHull2Subsequence
 
-The function `ch_graham_andrew_scan()` generates the counterclockwise sequence of extreme 
-points from a given set of input points that are not left of the line defined 
-by the first and last points in this sequence. 
+generates the counterclockwise sequence of extreme
+points from a given sequence of input points that are not left of the line defined
+by the first and last points in this sequence.
+
+More precisely, it generates the counterclockwise sequence of extreme
+points from a given sequence of input points that are not left of the line
+\f$ pq\f$ defined by the first (\f$p\f$) and last (\f$q\f$) points
+in this sequence (\f$ p\f$ is the value of `first` and \f$ q\f$ is
+the value of `beyond` \f$ -1\f$).
+The resulting sequence is placed
+starting at `result` with \f$ p\f$; point \f$ q\f$ is omitted.
+The past-the-end iterator for the sequence is returned.
+
+\pre The range [`first`,`beyond`) contains at least two different points. The points in [`first`,`beyond`) are sorted with respect to \f$ pq\f$, <I>i.e.</I>, the sequence of points in [`first`,`beyond`) define a counterclockwise polygon, for which the Graham-Sklansky-procedure \cgalCite{s-mcrm-72} works.
 
 The default traits class `Default_traits` is the kernel in which the 
 type `BidirectionalIterator::value_type` is defined. 
@@ -92,13 +103,12 @@ functions that return instances of these types:
 
 \cgalHeading{Implementation}
 
-The function uses Andrew's 
-variant of the Graham scan algorithm \cgalCite{a-aeach-79}. This algorithm 
-requires \f$ O(n \log n)\f$ time in the worst case for \f$ n\f$ input points. 
+This algorithm requires \f$ O(n)\f$ time in the worst case for
+\f$ n\f$ input points.
 
 \cgalHeading{Example}
 
-In the following example `ch_graham_andrew_scan()` is used to 
+In the example \ref Convex_hull_2/ch_graham_anderson.cpp, `ch_graham_andrew_scan()` is used to
 realize Anderson's variant \cgalCite{a-readc-78} of the Graham Scan 
 \cgalCite{g-eadch-72}. The points are sorted counterclockwise around the leftmost 
 point using the `Less_rotate_ccw_2` predicate, as defined in 
@@ -110,37 +120,6 @@ sorted sequence. It is not hard to see that the preconditions of
 Graham scan is usually inferior to Andrew's variant because of its higher 
 arithmetic demand. 
 
-\code
-template <class InputIterator, class OutputIterator, class Traits> 
-OutputIterator 
-ch_graham_anderson( InputIterator first, InputIterator beyond, 
-OutputIterator result, const Traits& ch_traits) 
-{ 
-typedef typename TraitsLess_xy_2 Less_xy_2; 
-typedef typename Traits::Point_2 Point_2; 
-typedef typename Traits::Less_rotate_ccw_2 Less_rotate_ccw_2; 
-
-if (first == beyond) return result; 
-std::vector< Point_2 > V; 
-copy( first, beyond, back_inserter(V) ); 
-typename std::vector< Point_2 >::iterator it = 
-std::min_element(V.begin(), V.end(), Less_xy_2()); 
-std::sort( V.begin(), V.end(), CGAL::bind_1(Less_rotate_ccw_2(), *it) ); 
-if ( *(V.begin()) == *(V.rbegin()) ) 
-{ 
-*result = *(V.begin()); ++result; 
-return result; 
-} 
-return ch_graham_andrew_scan( V.begin(), V.end(), result, ch_traits); 
-} 
-\endcode
-
-generates the counterclockwise sequence of extreme points that are
-not left of \f$ pq\f$, where \f$ p\f$ is the value of `first` and \f$ q\f$ is
-the value of `beyond` \f$ -1\f$. The resulting sequence is placed
-starting at `result` with \f$ p\f$; point \f$ q\f$ is omitted. The
-past-the-end iterator for the sequence is returned.
-\pre The range [`first`,`beyond`) contains at least two different points. The points in [`first`,`beyond`) are sorted with respect to \f$ pq\f$, <I>i.e.</I>, the sequence of points in [`first`,`beyond`) define a counterclockwise polygon, for which the Graham-Sklansky-procedure \cgalCite{s-mcrm-72} works.
 */
 template <class BidirectionalIterator, class OutputIterator, 
 class Traits>

Convex_hull_2/doc/Convex_hull_2/CGAL/ch_jarvis.h

@@ -60,9 +60,16 @@ namespace CGAL {
 /*!
 \ingroup PkgConvexHull2Subsequence
 
-Generates the counterclockwise sequence of extreme 
+generates the counterclockwise sequence of extreme 
 points from a given set of input points that line between two input points. 
 
+More precisely, it generates the counterclockwise subsequence of
+extreme points between `start_p` and `stop_p` of the 
+points in the range [`first`,`beyond`), starting at 
+position `result` with point `start_p`. The last point 
+generated is the point preceding `stop_p` in the 
+counterclockwise order of extreme points.
+
 The default traits class `Default_traits` is the kernel in which the 
 type `ForwardIterator::value_type` is defined. 
 
@@ -90,14 +97,7 @@ functions that return instances of these types:
 
 The function uses the Jarvis march (gift-wrapping) algorithm \cgalCite{j-ichfs-73}. 
 This algorithm requires \f$ O(n h)\f$ time in the worst
-case for \f$ n\f$ input points with \f$ h\f$ extreme points.
-
-generates the counterclockwise subsequence of
-extreme points between `start_p` and `stop_p` of the 
-points in the range [`first`,`beyond`), starting at 
-position `result` with point `start_p`. The last point 
-generated is the point preceding `stop_p` in the 
-counterclockwise order of extreme points.
+case for \f$ n\f$ input points with \f$ h\f$ extreme points
 
 \pre `start_p` and `stop_p` are extreme points with respect to
 the points in the range [`first`,`beyond`) and `stop_p`

Convex_hull_2/doc/Convex_hull_2/CGAL/convex_hull_2.h

@@ -81,10 +81,10 @@ namespace CGAL {
 /*!
 \ingroup PkgConvexHull2Subsequence
 
-The function `lower_hull_points_2()` generates the counterclockwise sequence of extreme 
+generates the counterclockwise sequence of extreme 
 points on the lower hull of a given set of input points. 
 
-It generates the counterclockwise sequence of extreme points
+More precisely, it generates the counterclockwise sequence of extreme points
 on the lower hull of the points in the range [`first`,
 `beyond`). The resulting sequence is placed starting at
 position `result`, and the past-the-end iterator for
@@ -145,10 +145,10 @@ namespace CGAL {
 /*!
 \ingroup PkgConvexHull2Subsequence
 
-The function `upper_hull_points_2()` generates the counterclockwise sequence of extreme 
+generates the counterclockwise sequence of extreme 
 points on the upper hull of a given set of input points. 
 
-It generates the counterclockwise sequence of extreme points
+More precisely, it generates the counterclockwise sequence of extreme points
 on the upper hull of the points in the range [`first`,
 `beyond`). The resulting sequence is placed starting at
 position `result`, and the past-the-end iterator for

Convex_hull_2/examples/Convex_hull_2/ch_graham_anderson.cpp

@@ -24,12 +24,15 @@ ch_graham_anderson( InputIterator  first, InputIterator  beyond,
   typename std::vector< Point_2 >::iterator it =
                std::min_element(V.begin(), V.end(), Less_xy_2());
   std::sort( V.begin(), V.end(), boost::bind(Less_rotate_ccw_2(), *it, _1, _2) );
-  if ( *(V.begin()) == *(V.rbegin()) )
+  if ( *(V.begin()) != *(V.rbegin()) )
   {
-      *result = *(V.begin());  ++result;
-      return result;
+    result = CGAL::ch_graham_andrew_scan( V.begin(), V.end(), result, ch_traits);
   }
-  return CGAL::ch_graham_andrew_scan( V.begin(), V.end(), result, ch_traits);
+  // add the last point of the sequence that is
+  // not added by ch_graham_andrew_scan
+  *result++ = *(V.rbegin());
+  return result;
+
 }
 
 int main()