Enhance doc for generic I/O functions

BGL/include/CGAL/boost/graph/IO/polygon_mesh_io.h

@@ -88,6 +88,8 @@ bool read_polygon_mesh(std::istream& is,
  * - \ref IOStreamGocad (`.ts`)
  * - \ref IOStreamVTK (`.vtp`)
  *
+ * The format is detected from the filename extension.
+ *
  * \tparam Graph a model of `MutableFaceGraph`
  * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters"
  *
@@ -206,6 +208,8 @@ bool read_polygon_mesh(const char* fname, Graph& g)
  * - \ref IOStreamGocad (`.ts`)
  * - \ref IOStreamVTK (`.vtp`)
  *
+ * The format is detected from the filename extension.
+ *
  * \tparam Graph a model of `FaceListGraph` and `HalfedgeListGraph`
  * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters"
  *

Point_set_3/include/CGAL/Point_set_3/IO.h

@@ -36,12 +36,13 @@ class Point_set_3;
 /*!
   \ingroup PkgPointSet3IO
 
-  \brief reads the point set from an input stream that can be either:
+  \brief reads the point set from an input stream.
 
-  - \link IOStreamXYZ XYZ \endlink
+  Supported file formats are the following:
-  - \link IOStreamOFF OFF \endlink
+  - \ref IOStreamOFF (`.off`)
-  - \link IOStreamPLY PLY \endlink
+  - \ref IOStreamPLY (`.ply`)
-  - \link IOStreamLAS LAS \endlink
+  - \ref IOStreamLAS (`.las`)
+  - \ref IOStreamXYZ (`.xyz`)
 
   The format is detected from the stream. If the stream contains
   normal vectors, the normal map is added to the point set. For PLY
@@ -84,12 +85,13 @@ std::istream& operator>>(std::istream& is,
 /*!
   \ingroup PkgPointSet3IO
 
-  \brief reads the point set from an input file that can be either:
+  \brief reads the point set from an input file.
 
-  - \link IOStreamXYZ XYZ \endlink
+  Supported file formats are the following:
-  - \link IOStreamOFF OFF \endlink
+  - \ref IOStreamOFF (`.off`)
-  - \link IOStreamPLY PLY \endlink
+  - \ref IOStreamPLY (`.ply`)
-  - \link IOStreamLAS LAS \endlink
+  - \ref IOStreamLAS (`.las`)
+  - \ref IOStreamXYZ (`.xyz`)
 
   The format is detected from the filename extension. If the file contains
   normal vectors, the normal map is added to the point set. For PLY
@@ -165,12 +167,13 @@ std::ostream& operator<<(std::ostream& os,
 /*!
   \ingroup PkgPointSet3IO
 
-  \brief inserts the point set in an output file that can be either:
+  \brief inserts the point set in an output file.
 
-  - \link IOStreamXYZ XYZ \endlink
+  Supported file formats are the following:
-  - \link IOStreamOFF OFF \endlink
+  - \ref IOStreamOFF (`.off`)
-  - \link IOStreamPLY PLY \endlink
+  - \ref IOStreamPLY (`.ply`)
-  - \link IOStreamLAS LAS \endlink
+  - \ref IOStreamLAS (`.las`)
+  - \ref IOStreamXYZ (`.xyz`)
 
   The format is detected from the filename extension.
 

Point_set_processing_3/include/CGAL/IO/read_points.h

@@ -31,12 +31,15 @@ namespace CGAL {
 /**
   \ingroup PkgPointSetProcessing3IO
 
-  Reads the point set from an input file that can be either:
+  \brief reads the point set from an input file.
 
-  - \link IOStreamXYZ XYZ \endlink
+  Supported file formats are the following:
-  - \link IOStreamOFF OFF \endlink
+  - \ref IOStreamOFF (`.off`)
-  - \link IOStreamPLY PLY \endlink
+  - \ref IOStreamPLY (`.ply`)
-  - \link IOStreamLAS LAS \endlink
+  - \ref IOStreamLAS (`.las`)
+  - \ref IOStreamXYZ (`.xyz`)
+
+  The format is detected from the filename extension.
 
   \tparam OutputIteratorValueType type of objects that can be put in `PointOutputIterator`.
   It is default to `value_type_traits<PointOutputIterator>::%type` and can be omitted when the default is fine.

Point_set_processing_3/include/CGAL/IO/write_points.h

@@ -36,18 +36,21 @@ namespace CGAL {
 /**
   \ingroup PkgPointSetProcessing3IO
 
-  Saves the range of `points` with properties to a file that can be either:
+  \brief saves the range of `points` with properties to a file.
 
-  - \link IOStreamXYZ XYZ \endlink
+  Supported file formats are the following:
-  - \link IOStreamOFF OFF \endlink
+  - \ref IOStreamOFF (`.off`)
-  - \link IOStreamPLY PLY \endlink
+  - \ref IOStreamPLY (`.ply`)
-  - \link IOStreamLAS LAS \endlink
+  - \ref IOStreamLAS (`.las`)
+  - \ref IOStreamXYZ (`.xyz`)
+
+  The format is detected from the filename extension.
 
   \tparam PointRange is a model of `ConstRange`. The value type of
   its iterator is the key type of the named parameter `point_map`.
   \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters"
 
-  \param fname the name of the input file.
+  \param fname the name of the output file.
   \param points the range of points that will be written.
   \param np optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below.
 
@@ -61,7 +64,7 @@ namespace CGAL {
     \cgalParamNBegin{normal_map}
       \cgalParamDescription{a property map associating normals to the elements of the poing range}
       \cgalParamType{a model of `ReadablePropertyMap` with value type `geom_traits::Vector_3`}
-      \cgalParamDefault{If this parameter is omitted, normals in the input stream are ignored.}
+      \cgalParamDefault{If this parameter is omitted, normals are not written in the output stream.}
     \cgalParamNEnd
 
     \cgalParamNBegin{geom_traits}

Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/IO/polygon_mesh_io.h

@@ -40,6 +40,16 @@ namespace Polygon_mesh_processing {
  * \brief Attempts to read a file as a polygon mesh; in case of failure, reads the file as a polygon soup,
  * repairs and orients it to obtain a polygon mesh.
  *
+ * Supported file formats are the following:
+ * - \ref IOStreamOFF (`.off`)
+ * - \ref IOStreamOBJ (`.obj`)
+ * - \ref IOStreamSTL (`.stl`)
+ * - \ref IOStreamPLY (`.ply`)
+ * - \ref IOStreamGocad (`.ts`)
+ * - \ref IOStreamVTK (`.vtp`)
+ *
+ * The format is detected from the filename extension.
+ *
  * \tparam PolygonMesh a model of `MutableFaceGraph`
  * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters"
  *
@@ -58,15 +68,6 @@ namespace Polygon_mesh_processing {
  *                     must be available in `PolygonMesh`.}
  *   \cgalParamNEnd
  *
- *   \cgalParamNBegin{geom_traits}
- *     \cgalParamDescription{an instance of a geometric traits class}
- *     \cgalParamType{The traits class must provide the nested functors `Less_xyz_3` and `Equal_3`
- *                    to respectivelycompare lexicographically two points and to check if two points
- *                    are identical. For each functor `Foo`, a function `Foo foo_object()` must be provided.}
- *     \cgalParamDefault{a \cgal Kernel deduced from the point type, using `CGAL::Kernel_traits`}
- *     \cgalParamExtra{The geometric traits class must be compatible with the vertex point type.}
- *   \cgalParamNEnd
- *
  *   \cgalParamNBegin{repair_polygon_soup}
  *     \cgalParamDescription{a parameter used indicate whether `CGAL::Polygon_mesh_processing::repair_polygon_soup()`
  *                           should be called on the soup in case of issues in the input.}
@@ -74,20 +75,10 @@ namespace Polygon_mesh_processing {
  *     \cgalParamDefault{`true`}
  *   \cgalParamNEnd
  *
- *   \cgalParamNBegin{erase_all_duplicates}
+ *   \cgalParamNBegin{verbose}
- *     \cgalParamDescription{Parameter to indicate, when multiple polygons are duplicates,
+ *     \cgalParamDescription{whether extra information is printed when an incident occurs during reading}
- *                           whether all the duplicate polygons should be removed
- *                           or if one (arbitrarily chosen) face should be kept.}
  *     \cgalParamType{Boolean}
- *     \cgalParamDefault{`false`}
+ *     \cgalParamDefault{`true`}
- *   \cgalParamNEnd
- *
- *   \cgalParamNBegin{require_same_orientation}
- *     \cgalParamDescription{Parameter to indicate if polygon orientation should be taken
- *                           into account when determining whether two polygons are duplicates,
- *                           that is, whether e.g. the triangles `0,1,2` and `0,2,1` are duplicates.}
- *     \cgalParamType{Boolean}
- *     \cgalParamDefault{`false`}
  *   \cgalParamNEnd
  * \cgalNamedParamsEnd
  *

Stream_support/include/CGAL/IO/polygon_soup_io.h

@@ -46,6 +46,8 @@ namespace CGAL {
  * - \ref IOStreamGocad (`.ts`)
  * - \ref IOStreamVTK (`.vtp`)
  *
+ * The format is detected from the filename extension.
+ *
  * \tparam PolygonRange a model of the concept `RandomAccessContainer`
  * whose value_type is a model of the concept `RandomAccessContainer`
  * whose value_type is `std::size_t`.
@@ -134,6 +136,8 @@ bool read_polygon_soup(const std::string& fname,
  * - \ref IOStreamGocad (`.ts`)
  * - \ref IOStreamVTK (`.vtp`)
  *
+ * The format is detected from the filename extension.
+ *
  * \tparam PolygonRange a model of the concept `RandomAccessContainer`
  * whose value_type is a model of the concept `RandomAccessContainer`
  * whose value_type is `std::size_t`.