From 9de30a6d563762b021bd73c1d979a1ca13724b34 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mael=20Rouxel-Labb=C3=A9?=
 <mael.rouxel.labbe@geometryfactory.com>
Date: Fri, 22 May 2020 18:57:16 +0200
Subject: [PATCH] Re-add doc of high level BGL I/O functions

---
 .../CGAL/boost/graph/IO/polygon_mesh_io.h     | 63 +++++++++++++++++--
 1 file changed, 59 insertions(+), 4 deletions(-)

diff --git a/BGL/include/CGAL/boost/graph/IO/polygon_mesh_io.h b/BGL/include/CGAL/boost/graph/IO/polygon_mesh_io.h
index 6bc5ac5bef9..8a2498a9a13 100644
--- a/BGL/include/CGAL/boost/graph/IO/polygon_mesh_io.h
+++ b/BGL/include/CGAL/boost/graph/IO/polygon_mesh_io.h
@@ -12,9 +12,11 @@
 
 #include <CGAL/boost/graph/io.h>
 
-//doc in doc/
+namespace CGAL {
 
-namespace CGAL{
+////////////////////////////////////////////////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////////////////////////////////////////////
+/// Read
 
 //not for now.
 /*
@@ -60,7 +62,34 @@ bool read_polygon_mesh(std::istream& is,
 }
 */
 
+/*!
+ * \ingroup PkgBGLIOFct
+ * \brief reads a polygon mesh from a file.
+ * \tparam FaceGraph a model of `FaceGraph`
+ * \tparam NamedParameters a sequence of \ref pmp_namedparameters "Named Parameters"
+ *
+ * \param fname the name of the file. Its extension must be one of the following :
+ * `.off` (\ref IOStreamOFF "OFF file format") , `.obj` (\ref IOStreamOBJ "OBJ file format"),
+ * `.stl` (\ref IOStreamSTL "STL file format"), `.ply` (\ref IOStreamPLY "PLY file format"),
+ * `.vtp`(\ref IOStreamVTK "VTP file format")  or `.ts`(\ref IOStreamGocad "GOCAD file format").
+ * \param g the mesh
+ * \param np optional \ref pmp_namedparameters "Named Parameters" described below
+ *
+ * \cgalNamedParamsBegin
+ * \cgalParamBegin{vertex_point_map} the property map with the points associated to the vertices of `g`.
+ *   If this parameter is omitted, an internal property map for
+ *   `CGAL::vertex_point_t` should be available in `FaceGraph`\cgalParamEnd
+ * \cgalNamedParamsEnd
+ * Other named parameters may be used according to the file extension.
+ * See `PkgBGLIOFct` for an exhaustive list.
 
+ * \return `true` if the reading worked, `false` otherwise.
+ *
+ * \pre The data must represent a 2-manifold
+ *
+ * \see \ref IOStreamOFF
+ *
+ */
 template <class FaceGraph, typename NamedParameters>
 bool read_polygon_mesh(const std::string& fname,
                        FaceGraph& g,
@@ -119,7 +148,34 @@ bool read_polygon_mesh(const char* fname,
   return read_polygon_mesh(fname, g, parameters::all_default());
 }
 
+////////////////////////////////////////////////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////////////////////////////////////////////
+/// Write
 
+/*!
+ * \ingroup PkgBGLIOFct
+ * \brief writes a polygon mesh in a file.
+ * \tparam FaceGraph a model of `FaceGraph`
+ * \tparam NamedParameters a sequence of \ref pmp_namedparameters "Named Parameters"
+ *
+ * \param fname the name of the file. Its extension must be one of the following :
+ * `.off` (\ref IOStreamOFF "OFF file format") , `.obj` (\ref IOStreamOBJ "OBJ file format"),
+ * `.stl` (\ref IOStreamSTL "STL file format"), `.ply` (\ref IOStreamPLY "PLY file format"),
+ * `.vtp`(\ref IOStreamVTK "VTP file format")  or `.ts`(\ref IOStreamGocad "GOCAD file format").
+ * \param g the mesh
+ * \param np optional \ref pmp_namedparameters "Named Parameters" described below
+ *
+ * \cgalNamedParamsBegin
+ * \cgalParamBegin{vertex_point_map} the property map with the points associated to the vertices of `g`.
+ *   If this parameter is omitted, an internal property map for
+ *   `CGAL::vertex_point_t` should be available in `FaceGraph`\cgalParamEnd
+ * \cgalNamedParamsEnd
+ * Other named parameters may be used according to the file extension.
+ * See `PkgBGLIOFct`  for an exhaustive list.
+ * \return `true` if the writing worked, `false` otherwise.
+ *
+ * \see \ref IOStreamOFF
+ */
 template <class FaceGraph, typename NamedParameters>
 bool write_polygon_mesh(const std::string& fname,
                        FaceGraph& g,
@@ -160,8 +216,6 @@ bool write_polygon_mesh(const std::string& fname,
   return write_polygon_mesh(fname, g, parameters::all_default());
 }
 
-
-
 template <class FaceGraph, typename NamedParameters>
 bool write_polygon_mesh(const char* fname,
                        FaceGraph& g,
@@ -176,6 +230,7 @@ bool write_polygon_mesh(const char* fname,
 {
   return write_polygon_mesh(fname, g, parameters::all_default());
 }
+
 }//end CGAL
 
 #endif // CGAL_BOOST_GRAPH_POLYGON_MESH_IO_H