Enhance doc for generic I/O functions

2020-07-17 13:37:37 +02:00 · 2020-07-17 13:37:37 +02:00 · 6d6d959d4d
parent f3659c5d96
commit 6d6d959d4d
6 changed files with 57 additions and 49 deletions
--- a/BGL/include/CGAL/boost/graph/IO/polygon_mesh_io.h
+++ b/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"
 *
--- a/Point_set_3/include/CGAL/Point_set_3/IO.h
+++ b/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
-  - \link IOStreamOFF OFF \endlink
-  - \link IOStreamPLY PLY \endlink
-  - \link IOStreamLAS LAS \endlink
+  Supported file formats are the following:
+  - \ref IOStreamOFF (`.off`)
+  - \ref IOStreamPLY (`.ply`)
+  - \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
-  - \link IOStreamOFF OFF \endlink
-  - \link IOStreamPLY PLY \endlink
-  - \link IOStreamLAS LAS \endlink
+  Supported file formats are the following:
+  - \ref IOStreamOFF (`.off`)
+  - \ref IOStreamPLY (`.ply`)
+  - \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
-  - \link IOStreamOFF OFF \endlink
-  - \link IOStreamPLY PLY \endlink
-  - \link IOStreamLAS LAS \endlink
+  Supported file formats are the following:
+  - \ref IOStreamOFF (`.off`)
+  - \ref IOStreamPLY (`.ply`)
+  - \ref IOStreamLAS (`.las`)
+  - \ref IOStreamXYZ (`.xyz`)

  The format is detected from the filename extension.

--- a/Point_set_processing_3/include/CGAL/IO/read_points.h
+++ b/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
-  - \link IOStreamOFF OFF \endlink
-  - \link IOStreamPLY PLY \endlink
-  - \link IOStreamLAS LAS \endlink
+  Supported file formats are the following:
+  - \ref IOStreamOFF (`.off`)
+  - \ref IOStreamPLY (`.ply`)
+  - \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.
--- a/Point_set_processing_3/include/CGAL/IO/write_points.h
+++ b/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
-  - \link IOStreamOFF OFF \endlink
-  - \link IOStreamPLY PLY \endlink
-  - \link IOStreamLAS LAS \endlink
+  Supported file formats are the following:
+  - \ref IOStreamOFF (`.off`)
+  - \ref IOStreamPLY (`.ply`)
+  - \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}
--- a/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/IO/polygon_mesh_io.h
+++ b/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}
- *     \cgalParamDescription{Parameter to indicate, when multiple polygons are duplicates,
- *                           whether all the duplicate polygons should be removed
- *                           or if one (arbitrarily chosen) face should be kept.}
+ *   \cgalParamNBegin{verbose}
+ *     \cgalParamDescription{whether extra information is printed when an incident occurs during reading}
 *     \cgalParamType{Boolean}
- *     \cgalParamDefault{`false`}
- *   \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`}
+ *     \cgalParamDefault{`true`}
 *   \cgalParamNEnd
 * \cgalNamedParamsEnd
 *
--- a/Stream_support/include/CGAL/IO/polygon_soup_io.h
+++ b/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`.