From efcb6c53784be4edbea59ff6522c8d41ebdd70a0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mael=20Rouxel-Labb=C3=A9?=
 <mael.rouxel.labbe@geometryfactory.com>
Date: Mon, 30 Dec 2019 18:29:03 +0100
Subject: [PATCH] Fix documentation of tds_data

tds_data is required from TDS3::Cell, not by a model of the cell base
of CGAL::T_D_S_3 (the model of TDS3).

It also must properly document its API.
---
 .../Concepts/TriangulationDSCellBase_3.h      | 25 -----
 .../Concepts/TriangulationDataStructure_3.h   | 95 +++++++++++++++++++
 TDS_3/doc/TDS_3/PackageDescription.txt        |  1 +
 3 files changed, 96 insertions(+), 25 deletions(-)

diff --git a/TDS_3/doc/TDS_3/Concepts/TriangulationDSCellBase_3.h b/TDS_3/doc/TDS_3/Concepts/TriangulationDSCellBase_3.h
index bee4962703f..3e0a7f86102 100644
--- a/TDS_3/doc/TDS_3/Concepts/TriangulationDSCellBase_3.h
+++ b/TDS_3/doc/TDS_3/Concepts/TriangulationDSCellBase_3.h
@@ -75,11 +75,6 @@ typedef TriangulationDataStructure_3::Vertex_handle Vertex_handle;
 */ 
 typedef TriangulationDataStructure_3::Cell_handle Cell_handle; 
 
-/*!
-
-*/ 
-typedef TriangulationDataStructure_3::Cell_data TDS_data; 
-
 /// @} 
 
 /// \name Creation 
@@ -236,26 +231,6 @@ void * & for_compact_container();
 
 /// @}
 
-/// \name Internal
-/// \cgalAdvancedBegin
-/// These functions are used internally by the triangulation data
-/// structure. The user is not encouraged to use them directly as they
-/// may change in the future.
-/// \cgalAdvancedEnd
-/// @{
-
-/*!
-
-*/ 
-TDS_data& tds_data(); 
-
-/*!
-
-*/ 
-const TDS_data& tds_data() const; 
-
-/// @}
-
 /// \name I/O
 /// @{
 
diff --git a/TDS_3/doc/TDS_3/Concepts/TriangulationDataStructure_3.h b/TDS_3/doc/TDS_3/Concepts/TriangulationDataStructure_3.h
index 175a64c4e20..76f560dad46 100644
--- a/TDS_3/doc/TDS_3/Concepts/TriangulationDataStructure_3.h
+++ b/TDS_3/doc/TDS_3/Concepts/TriangulationDataStructure_3.h
@@ -90,6 +90,11 @@ typedef unspecified_type Vertex;
 */
 typedef unspecified_type Cell;
 
+/*!
+  %Cell data type, requirements are described in `TriangulationDataStructure_3::Cell_data`.
+*/
+typedef unspecified_type Cell_data;
+
 /*!
 Size type (unsigned integral type) 
 */ 
@@ -1161,6 +1166,7 @@ In order to obtain new cells or destruct unused cells, the user must call the
 structure. 
 
 \sa `TriangulationDataStructure_3::Vertex`
+\sa `TriangulationDataStructure_3::Cell_data`
 
 */
 
@@ -1185,6 +1191,11 @@ typedef TriangulationDataStructure_3::Vertex_handle Vertex_handle;
 */ 
 typedef TriangulationDataStructure_3::Cell_handle Cell_handle; 
 
+/*!
+
+*/
+typedef TriangulationDataStructure_3::Cell_data TDS_data;
+
 /// @} 
 
 /// \name Access Functions 
@@ -1272,6 +1283,26 @@ Cell_handle n3);
 
 /// @} 
 
+/// \name Internal
+/// \cgalAdvancedBegin
+/// These functions are used internally by the triangulation data
+/// structure. The user is not encouraged to use them directly as they
+/// may change in the future.
+/// \cgalAdvancedEnd
+/// @{
+
+/*!
+
+*/
+TDS_data& tds_data();
+
+/*!
+
+*/
+const TDS_data& tds_data() const;
+
+/// @}
+
 /// \name Checking 
 /// @{
 
@@ -1286,3 +1317,67 @@ bool is_valid(bool verbose = false, int level = 0) const;
 /// @}
 
 }; /* end Cell */
+
+
+/*!
+\ingroup PkgTDS3Concepts
+\cgalConcept
+
+Various algorithms using a triangulation data structure, such as Delaunay triangulations
+or Alpha Shapes, must be able to associate a state to a cell elemental.
+For efficiency, this information must be stored directly within the cell.
+
+This class is only meant to store a state (Boolean). Consequently, the state must be the default
+value (i.e. `false`) unless a setting function (`mark_in_conflict()`, etc.) has been called.
+
+The three states are "in conflict", "on boundary", and "processed".
+By default, a cell is not in conflict, not on boundary, and not processed.
+
+\sa `TriangulationDataStructure_3::Cell`
+
+*/
+
+class TriangulationDataStructure_3::Cell_data
+{
+public:
+  /// \name Setting
+  /// @{
+
+  /// Clears all flags: the cell is neither in conflict, nor on the boundary, nor processed.
+  void clear();
+
+  /// Sets the "in conflict" state to `true`.
+  ///
+  /// \post `is_in_conflict()` returns `true`
+  void mark_in_conflict();
+
+  /// Sets the "on boundary" state to `true`.
+  ///
+  /// \post `is_on_boundary()` returns `true`
+  void mark_on_boundary();
+
+  /// Sets the "processed" state to `true`.
+  ///
+  /// \post `processed()` returns `true`
+  void mark_processed();
+
+  /// @}
+
+  /// \name Access Functions
+  /// @{
+
+  /// Checks whether the cell has default state (not in conflict, not on boundary, not processed).
+  bool is_clear();
+
+  /// Returns whether the cell has been marked as "in conflict".
+  bool is_in_conflict();
+
+  /// Returns whether the cell has been marked as "on boundary".
+  bool is_on_boundary();
+
+  /// Returns whether the cell has been marked as "processed".
+  bool processed();
+
+  /// @}
+
+}; /* end Cell_data */
diff --git a/TDS_3/doc/TDS_3/PackageDescription.txt b/TDS_3/doc/TDS_3/PackageDescription.txt
index 9bde710fa0d..ec963cff969 100644
--- a/TDS_3/doc/TDS_3/PackageDescription.txt
+++ b/TDS_3/doc/TDS_3/PackageDescription.txt
@@ -50,6 +50,7 @@ Section  \ref TDS3secintro.)
 
 - `TriangulationDataStructure_3`
 - `TriangulationDataStructure_3::Cell`
+- `TriangulationDataStructure_3::Cell_data`
 - `TriangulationDataStructure_3::Vertex`
 - `TriangulationDSCellBase_3`
 - `TriangulationDSVertexBase_3`