Rephrase warning about std::ios::binary + add missing (LAS - always binary)

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

@@ -83,7 +83,7 @@ bool read_PLY_BGL(std::istream& is,
 
   \brief reads the graph `g` from the input stream, using the \ref IOStreamPLY.
 
-  \attention Be mindful of the flag `std::ios::binary` flag when creating the `ifstream` when reading a binary file.
+  \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`.
 
   \tparam Graph a model of `MutableFaceGraph`
   \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters"
@@ -281,7 +281,7 @@ bool read_PLY(const std::string& fname, Graph& g,
 
  \brief writes the graph in an output stream, using the \ref IOStreamPLY.
 
- \attention Be mindful of the flag `std::ios::binary` flag when creating the `ofstream` when writing a binary file.
+ \attention When writing a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ofstream`.
 
  \tparam Graph a model of `FaceListGraph`
  \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters"

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

@@ -70,10 +70,10 @@ public:
 
   \brief reads the graph `g` from the input stream, using the \ref IOStreamSTL.
 
-  \attention Be mindful of the flag `std::ios::binary` flag when creating the `ifstream` when reading a binary file.
-
   \attention The graph `g` is not cleared, and the data from the stream is added.
 
+  \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`.
+
   \tparam Graph a model of `MutableFaceGraph`
   \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters"
 
@@ -203,7 +203,7 @@ bool read_STL(const std::string& fname, Graph& g) { return read_STL(fname, g, pa
 
   \brief writes the graph `g` in the output stream `os`, using the \ref IOStreamSTL.
 
-  \attention Be mindful of the flag `std::ios::binary` flag when creating the `ofstream` when writing a binary file.
+  \attention When writing a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ofstream`.
 
   \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/LAS.h

@@ -63,6 +63,8 @@ void check_if_property_is_used(PointSet& point_set,
 
   \brief reads the content of an intput stream in the \ref IOStreamLAS into a point set.
 
+  \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`.
+
   \tparam Point a `CGAL::Point_3`
   \tparam Vector a `CGAL::Vector_3`
 
@@ -213,6 +215,8 @@ CGAL_DEPRECATED bool read_las_point_set(std::istream& is, ///< input stream.
 
   \brief writes the content of a point set into an output stream in the \ref IOStreamLAS.
 
+  \attention When writing a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ofstream`.
+
   \tparam Point a `CGAL::Point_3`
   \tparam Vector a `CGAL::Vector_3`
   \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters"

Point_set_3/include/CGAL/Point_set_3/IO/PLY.h

@@ -238,7 +238,7 @@ public:
   header. Each line starting by "comment " in the header is
   appended to the `comments` string (without the "comment " word).
 
-  \attention Be mindful of the flag `std::ios::binary` flag when creating the `ifstream` when reading a binary file
+  \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`.
 
   \tparam Point a `CGAL::Point_3`
   \tparam Vector a `CGAL::Vector_3`
@@ -466,6 +466,8 @@ CGAL_DEPRECATED bool read_ply_point_set(std::istream& is, ///< input stream.
   the header of the PLY stream (each line will be precedeed by
   "comment ").
 
+  \attention When writing a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ofstream`.
+
   \tparam Point a `CGAL::Point_3`
   \tparam Vector a `CGAL::Vector_3`
   \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters"
@@ -483,8 +485,6 @@ CGAL_DEPRECATED bool read_ply_point_set(std::istream& is, ///< input stream.
    \cgalParamNEnd
   \cgalNamedParamsEnd
 
-  \attention Be mindful of the flag `std::ios::binary` flag when creating the `ofstream` when writing a binary file
-
   \return `true` if the reading was successful, `false` otherwise.
 */
 template <typename Point, typename Vector, typename CGAL_BGL_NP_TEMPLATE_PARAMETERS>

Point_set_processing_3/include/CGAL/IO/read_las_points.h

@@ -363,6 +363,8 @@ void process_properties (const LASpoint& reader, OutputValueType& new_element,
    - `LAS_property::B` with type `unsigned short`
    - `LAS_property::I` with type `unsigned short`
 
+   \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`.
+
    \tparam OutputIteratorValueType type of objects that can be put in `OutputIterator`.
    It is default to `value_type_traits<OutputIterator>::%type` and can be omitted when the default is fine.
    \tparam OutputIterator iterator over output points.
@@ -427,6 +429,8 @@ bool read_LAS_with_properties(std::istream& is,
 
    Potential additional properties are ignored.
 
+   \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`.
+
    \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.
    \tparam PointOutputIterator iterator over output points.

Point_set_processing_3/include/CGAL/IO/read_ply_points.h

@@ -202,7 +202,7 @@ bool read_PLY_with_properties(std::istream& is,
 
    Potential additional point properties and faces are ignored.
 
-   \attention Be mindful of the flag `std::ios::binary` flag when creating the `ifstream` when reading a binary file
+   \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`.
 
    \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_las_points.h

@@ -174,6 +174,8 @@ namespace LAS {
    See documentation of `read_LAS_with_properties()` for the
    list of available `LAS_property::Tag` classes.
 
+   \attention When writing a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ofstream`.
+
    \tparam PointRange is a model of `ConstRange`. The value type of
    its iterator is the key type of the named parameter `point_map`.
    \tparam PointMap is a model of `ReadablePropertyMap` with a value_type = `CGAL::Point_3`.
@@ -248,7 +250,9 @@ bool write_LAS_with_properties(std::ostream& os, ///< output stream.
 /**
    \ingroup PkgPointSetProcessing3IOLas
 
-   Saves the range of `points` (positions only) using the \ref IOStreamLAS.
+   \brief Saves the range of `points` (positions only) using the \ref IOStreamLAS.
+
+   \attention When writing a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ofstream`.
 
    \tparam PointRange is a model of `ConstRange`. The value type of
    its iterator is the key type of the named parameter `point_map`.

Point_set_processing_3/include/CGAL/IO/write_ply_points.h

@@ -145,7 +145,7 @@ template <typename PointRange,
 
    %PLY is either ASCII or binary depending on the value of `CGAL::get_mode(os)`.
 
-   \attention Be mindful of the flag `std::ios::binary` flag when creating the `ofstream` when writing a binary file.
+   \attention When writing a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ofstream`.
 
    \tparam PointRange is a model of `ConstRange`. The value type of
    its iterator is the key type of the named parameter `point_map`.

Stream_support/include/CGAL/IO/PLY.h

@@ -274,7 +274,7 @@ bool read_PLY(std::istream& is,
  *
  * \brief reads the content of `is` into `points` and `polygons`, using the \ref IOStreamPLY.
  *
- * \attention Be mindful of the flag `std::ios::binary` flag when creating the `ifstream` when reading a binary file.
+ * \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`.
  *
  * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type.
  * \tparam PolygonRange a model of the concept `SequenceContainer`
@@ -432,9 +432,9 @@ bool read_PLY(const std::string& fname, PointRange& points, PolygonRange& polygo
 /*!
  * \ingroup PkgStreamSupportIoFuncsPLY
  *
- * writes the content of `points` and `polygons` in `out`, using the \ref IOStreamPLY.
+ * \brief writes the content of `points` and `polygons` in `out`, using the \ref IOStreamPLY.
  *
- * \attention Be mindful of the flag `std::ios::binary` flag when creating the `ofstream` when writing a binary file.
+ * \attention When writing a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ofstream`.
  *
  * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type.
  * \tparam PolygonRange a model of the concept `SequenceContainer`

Stream_support/include/CGAL/IO/STL.h

@@ -45,7 +45,7 @@ namespace CGAL {
  *
  * \brief reads the content of `is` into `points` and `facets`, using the \ref IOStreamSTL.
  *
- * \attention Be mindful of the flag `std::ios::binary` flag when creating the `ifstream` when reading a binary file.
+ * \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`.
  *
  * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type.
  * \tparam TriangleRange a model of the concept `SequenceContainer`
@@ -258,9 +258,9 @@ bool read_STL(const std::string& fname, PointRange& points, TriangleRange& facet
 /*!
  * \ingroup PkgStreamSupportIoFuncsSTL
  *
- * writes the content of `points` and `facets` in `os`, using the \ref IOStreamSTL.
+ * \brief writes the content of `points` and `facets` in `os`, using the \ref IOStreamSTL.
  *
- * \attention Be mindful of the flag `std::ios::binary` flag when creating the `ofstream` when writing a binary file.
+ * \attention When writing a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ofstream`.
  *
  * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is the point type.
  * \tparam TriangleRange a model of the concept `SequenceContainer`

Surface_mesh/include/CGAL/Surface_mesh/IO/PLY.h

@@ -714,7 +714,7 @@ void fill_header(std::ostream& os, const Surface_mesh<Point>& sm,
 
 /// \ingroup PkgSurfaceMeshIOFuncPLY
 ///
-/// \attention Be mindful of the flag `std::ios::binary` flag when creating the `ifstream` when reading a binary file.
+/// \attention When reading a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ifstream`.
 ///
 /// \brief extracts the surface mesh from an input stream in the \ref IOStreamPLY
 ///        and appends it to the surface mesh `sm`.
@@ -883,7 +883,7 @@ CGAL_DEPRECATED bool read_ply(std::istream& is, Surface_mesh<P>& sm, std::string
 /// simple types are inserted in the stream. The halfedges follow
 /// the same behavior.
 ///
-/// \attention Be mindful of the flag `std::ios::binary` flag when creating the `ofstream` when writing a binary file.
+/// \attention When writing a binary file, the flag `std::ios::binary` flag must be set during the creation of the `ofstream`.
 ///
 /// \tparam Point The type of the \em point property of a vertex. There is no requirement on `P`,
 ///               besides being default constructible and assignable.