fix minor issues with code and doc regarding the locate() functions

Triangulation/doc_tex/Triangulation_ref/Triangulation.tex

@@ -328,7 +328,13 @@ the triangulation:
 
 \ccMethod{Full_cell_handle locate(const Point & query,
 Full_cell_handle hint = Full_cell_handle()) const;}
-{If the point \ccc{query} lies in the interior of a bounded (finite) full cell of \ccVar,
+{The optional argument \ccc{hint} is used as a starting place for the search.\\
+If the \ccc{query} point lies outside the affine hull of the points (which can
+happen when \ccVar.\ccc{current_dimension() < }
+\ccVar.\ccc{maximal_dimension()}) or if there is no finite vertex yet in the
+triangulation, then \textit{locate} returns a default constructed
+\ccc{Full_cell_handle()}.\\
+If the point \ccc{query} lies in the interior of a bounded (finite) full cell of \ccVar,
 the latter full cell is returned.\\
 If \ccc{query} lies on the boundary of some finite full cells, one of them
 is returned.\\
@@ -336,8 +342,7 @@ Let $d=$\ccVar.\ccc{current_dimension()}. If the point \ccc{query} lies
 outside the convex hull of the points, an infinite full cell with vertices $\{
 p_1, p_2, \ldots, p_d, \infty\}$ is returned such that the full cell $(p_1, p_2,
 \ldots, p_d, query)$ is positively oriented (the rest of the triangulation lies
-on the other side of facet $(p_1, p_2, \ldots, p_d)$).\\
+on the other side of facet $(p_1, p_2, \ldots, p_d)$).}
-The optional argument \ccc{hint} is used as a starting place for the search.}
 
 \ccMethod{Full_cell_handle locate(const Point & query, Vertex_handle hint)
 const;}
@@ -346,12 +351,11 @@ const;}
 \ccMethod{Full_cell_handle locate(const Point & query, Locate_type & loc_type,
 Face & f, Facet & ft, Full_cell_handle hint = Full_cell_handle()) const;}
 {The optional argument \ccc{hint} is used as a starting place for the
-search.\\ If the \ccc{query} point lies outside the affine hull of the points,
+search.\\ If the \ccc{query} point lies outside the affine hull of the points
-which can happen when \ccVar.\ccc{current_dimension() < }
+(which can happen when \ccVar.\ccc{current_dimension() < }
-\ccVar.\ccc{maximal_dimension()}, \ccc{loc_type} is set to
+\ccVar.\ccc{maximal_dimension()}) or if there is no finite vertex yet in the
-\ccc{OUTSIDE_AFFINE_HULL}, and the returned full cell has no meaning. As a
+triangulation, then \ccc{loc_type} is set to
-particular case, if there is no finite vertex yet in the triangulation,
+\ccc{OUTSIDE_AFFINE_HULL}, and \textit{locate} returns
-\ccc{loc_type} is set to \ccc{OUTSIDE_AFFINE_HULL} and \textit{locate} returns
 \ccc{Full_cell_handle()}.\\ If the \ccc{query} point lies inside the affine hull
 of the points, a $k$-face that contains \ccc{query} {in its relative
 interior} is returned. (If the $k$-face is finite, it is
@@ -376,7 +380,9 @@ the \ccc{query} point is returned. \end{itemize}}
 \ccMethod{Full_cell_handle
           locate(const Point & query, Locate_type & loc_type,
                  Face & f, Vertex_handle hint) const;}
-{Same as above but \ccc{hint}, the starting place for the search is a vertex.}
+{Same as above but \ccc{hint}, the starting place for the search, is a vertex.
+The parameter \ccc{hint} is ignored if it is a default constructed
+\ccc{Vertex_handle()}.}
 
 \ccHeading{Removal} % - - - - - - - - - - - - - - - - - - - - - - - REMOVALS
 

Triangulation/include/CGAL/Delaunay_triangulation.h

@@ -464,9 +464,12 @@ Delaunay_triangulation<DCTraits, TDS>
                 tds().associate_vertex_with_full_cell(*it, v_idx, infinite_vertex());
                 if( v_idx != 0 )
                 {
-                    // we must put the infinite vertex at index 0
+                    // we must put the infinite vertex at index 0.
+                    // OK, now with the new convention that the infinite vertex
+                    // does not have to be at index 0, this is not necessary,
+                    // but still, I prefer to keep this piece of code here. [-- Samuel Hornus]
                     (*it)->swap_vertices(0, v_idx);
-                    // FIXME: are we sure this preseves the positive orientation of the full_cell ?
+                    // Now, we preserve the positive orientation of the full_cell
                     (*it)->swap_vertices(current_dimension() - 1, current_dimension());
                 }
             }
@@ -654,6 +657,7 @@ Delaunay_triangulation<DCTraits, TDS>
     side_of_oriented_subsphere_predicate() = geom_traits().side_of_oriented_subsphere_d_object();
     if( 1 <= current_dimension() )
     {
+        // FIXME: infinite vertex is NOT at index 0 a priori.
         Full_cell_handle s = infinite_vertex()->full_cell()->neighbor(0);
         Orientation o = orientation(s);
         CGAL_assertion( ZERO != o );
@@ -713,6 +717,7 @@ Delaunay_triangulation<DCTraits, TDS>
     v->set_point(p);
     if( current_dimension() >= 1 )
     {
+        // FIXME: infinite vertex is NOT at index 0 a priori.
         Full_cell_handle s = infinite_vertex()->full_cell()->neighbor(0);
         Orientation o = orientation(s);
         CGAL_assertion( ZERO != o );

Triangulation/include/CGAL/Triangulation.h

@@ -593,11 +593,13 @@ public:
             Full_cell_handle n = s->neighbor(i);
             if( ! t_.is_infinite(n) )
                 return false;
+            // FIXME: infinite vertex is NOT at index 0 a priori.
             n->vertex(0)->set_point(p_);
             bool ok = (POSITIVE == ori_(t_.points_begin(n), t_.points_begin(n) + cur_dim_ + 1));
             return ok;
         }
     };
+
     // make sure all full_cells have positive orientation
     void reorient_full_cells();
 
@@ -745,6 +747,7 @@ Triangulation<TT, TDS>
     // infinite one...
     CGAL_precondition( is_infinite(s) );
     CGAL_precondition( 1 == current_dimension() );
+    // FIXME: infinite vertex is NOT at index 0 a priori. But I'm not sure it's a problem here.
     bool swap = (0 == s->neighbor(0)->index(s));
     Vertex_handle v = tds().insert_in_full_cell(s);
     v->set_point(p);
@@ -782,6 +785,7 @@ Triangulation<TT, TDS>
             ochtp(*this, p, ori);
         tds().gather_full_cells(s, ochtp, out);
     }
+    // FIXME: infinite vertex is NOT at index 0 a priori.
     Vertex_handle v = insert_in_hole(p, simps.begin(), simps.end(), Facet(s, 0));
     return v;
 }
@@ -798,6 +802,7 @@ Triangulation<TT, TDS>
     v->set_point(p);
     if( current_dimension() >= 1 )
     {
+        // FIXME: infinite vertex is NOT at index 0 a priori.
         Full_cell_handle s = infinite_vertex()->full_cell()->neighbor(0);
         Orientation o = orientation(s);
         CGAL_assertion( COPLANAR != o );
@@ -835,15 +840,16 @@ Triangulation<TT, TDS>
         if( EQUAL != geom_traits().compare_lexicographically_d_object()(p, vit->point()) )
         {
             loc_type = OUTSIDE_AFFINE_HULL;
+            return Full_cell_handle();
         }
         else
         {
             loc_type = ON_VERTEX;
             face.set_full_cell(vit->full_cell());
             face.set_index(0, 0);
-        }
             return vit->full_cell();
         }
+    }
 
     Full_cell_handle s;
 
@@ -851,12 +857,13 @@ Triangulation<TT, TDS>
     if( Full_cell_handle() == start )
         // THE HACK THAT NOBODY SHOULD DO... BUT DIFFICULT TO WORK AROUND
         // THIS... TODO: WORK AROUND IT
+        // FIXME: infinite vertex is NOT at index 0 a priori.
         s = const_cast<Self*>(this)->infinite_full_cell()->neighbor(0);
     else
     {
         s = start;
         if( is_infinite(s) )
-            s = s->neighbor(0);
+            s = s->neighbor(0); // FIXME: index of infinite vertex is not zero ( not 0)
     }
 
     // Check if query |p| is outside the affine hull
@@ -1206,7 +1213,7 @@ operator<<(std::ostream & os, const Triangulation<TT, TDS> & tr)
     // write the vertices
     std::map<Vertex_handle, int> index_of_vertex;
 
-    // infinite vertex has index 0
+    // infinite vertex has index 0 (among all the vertices)
     index_of_vertex[tr.infinite_vertex()] = i++;
     os << *tr.infinite_vertex();
     for( Vertex_iterator it = tr.vertices_begin(); it != tr.vertices_end(); ++it )