update orientation and stitch doc

Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/orientation.h

@@ -55,31 +55,31 @@ namespace internal{
 
 /**
  * \ingroup PkgPolygonMeshProcessing
- * tests whether a closed surface polygon mesh has a positive orientation.
- * A polygon mesh is considered to have positive orientation if the normal vectors
- * of the facets point outside the domain described by the polygon mesh. For each facet, its normal vector
- * is considered to point on the side of the facet where the sequence of vertices of
+ * tests whether a closed polygon mesh has a positive orientation.
+ * A closed polygon mesh is considered to have a positive orientation if the normal vectors
+ * of its faces point outside the domain bounded by the polygon mesh. For each face, its normal vector
+ * is considered to point on the side of the face where the sequence of vertices of
  * the facet is seen counterclockwise.
- * @pre @a `pmesh` is closed
- * @pre @a `pmesh` is consistently oriented
+ * @pre `CGAL::is_closed(pmesh)`
+ * @pre If `pmesh` contains several connected components they are oriented consistentl,
+ *      that is the answer to this predicate would be the same if called on each
+ *       connected component isolated.
  *
  * @tparam PolygonMesh a model of `FaceListGraph`
  * @tparam VertexPointMap a model of `ReadablePropertyMap` with
     `boost::graph_traits<PolygonMesh>::%vertex_descriptor` as key type and
     `Kernel::Vector_3` as value type
- * @tparam Kernel Geometric traits class. It can be omitted and deduced automatically from the point type of `PolygonMesh`.
+ * @tparam Kernel Geometric traits class.
  *
- * @param pmesh a closed polygon mesh to be tested
+ * @param pmesh the closed polygon mesh to be tested
  * @param vpmap the property map with the points associated to the vertices of `pmesh`
- * @param k a traits class instance, can be omitted
+ * @param k a traits class instance
  *
  * \todo The following only handles polyhedron with one connected component
  *       the code, the sample example and the plugin must be updated.
- * @code
- * if(!is_outward_oriented(pmesh)) {
- *   reverse_face_orientations(pmesh);
- * }
- * @endcode
+ *
+ *  \sa `CGAL::Polygon_mesh_processing::reverse_face_orientations()`
+ *
  */
 template<typename PolygonMesh
        , typename VertexPointMap
@@ -89,7 +89,7 @@ template<typename PolygonMesh
        , typename Kernel
 #ifdef DOXYGEN_RUNNING
        = typename Kernel_traits<
-           typename boost::property_traits<VertexPointMap>::value_type>::Kernel
+           typename boost::property_traits<VertexPointMap>::value_type>::type
 #endif
          >
 bool is_outward_oriented(const PolygonMesh& pmesh
@@ -176,9 +176,7 @@ void reverse_orientation(typename boost::graph_traits<PolygonMesh>::halfedge_des
 
 /**
 * \ingroup PkgPolygonMeshProcessing
-* reverses faces orientations.
-*
-* @pre @a `pmesh` is consistently oriented
+* reverses for each face the order of the vertices along the face boundary.
 *
 * @tparam PolygonMesh a model of `FaceListGraph`
 */

Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/stitch_borders.h

@@ -251,6 +251,7 @@ private:
 /// The halfedges to be stitched are provided in `hedge_pairs_to_stitch`.
 /// For each pair `p` in this vector, p.second and its opposite will be removed
 /// from `pmesh`.
+///
 /// The vertices that get removed from `pmesh` are selected as follows:
 /// The pair of halfedges in `hedge_pairs_to_stitch` are processed linearly.
 /// Let `p` be such a pair.
@@ -258,11 +259,11 @@ private:
 /// then the source of p.second is.
 /// If the target of p.second has not been marked for deletion,
 /// then the source of p.first is.
-
+///
 /// @tparam PolygonMesh a model of `MutableFaceGraph` and `FaceListGraph`
 /// @tparam VertexPointMap property map with `boost::graph_traits<FaceGraph>::%vertex_descriptor`
 ///    as key type and a `PolygonMesh::Point` as value type
-
+///
 /// @param pmesh the polygon mesh to be modified by stitching
 /// @param hedge_pairs_to_stitch a `std::vector` filled with `std::pair`s of halfedges to be stitched together
 /// @param vpmap the property map with the points associated to the vertices of `pmesh`.
@@ -302,9 +303,9 @@ void stitch_borders(
 ///\endcond
 
 /// \ingroup stitching_grp
-/// Same as above but the pairs of halfedges to be stitched are found
+/// Same as the other overload but the pairs of halfedges to be stitched are found
 /// using `less_hedge`. Two halfedges `h1` and `h2` are set to be stitched
-/// if `less_hedge(h1,h2)=less_hedge(h2,h1)=true`.
+/// if `less_hedge(h1,h2)==less_hedge(h2,h1)==true`.
 
 /// @tparam LessHedge a key comparison functor used to sort halfedges.
 ///   It should be able to compare `boost::graph_traits<PolygonMesh>::%halfedge_descriptor`