twagraph: improve doc

Based on report by Michaël Cadilhac.

* spot/graph/graph.hh, spot/twa/twagraph.hh (defrag_state): Clarify
that only unreachable states are meant to be removed.
* spot/twa/twagraph.hh (merge_edges): Typo in comment.  Fixes #457.
* THANKS: Add Michaël.

THANKS

@@ -33,6 +33,7 @@ Kristin Y. Rozier
 Martin Dieguez Lodeiro
 Matthias Heizmann
 Maxime Bouton
+Michaël Cadilhac
 Michael Tautschnig
 Michael Weber
 Mikuláš Klokočka

spot/graph/graph.hh

@@ -1289,10 +1289,19 @@ namespace spot
 
     /// \brief Rename and remove states.
     ///
-    /// \param newst A vector indicating how each state should be renumbered.
+    /// This method is used to remove some states that have been
-    /// Use -1U to erase a state.  All other numbers are expected to
+    /// previously detected to be unreachable in order to "defragment"
-    /// satisfy newst[i] ≤ i for all i.
+    /// the state vector.  When a state is removed, all its outgoing
-    /// \param used_states the number of states used (after renumbering)
+    /// transition are removed as well.  Removing reachable states
+    /// should NOT be attempted, because the incoming edges will be
+    /// dangling.
+    ///
+    /// \param newst A vector indicating how each state should be
+    /// renumbered.  Use -1U to erase an unreachable state.  All other
+    /// numbers are expected to satisfy newst[i] ≤ i for all i.
+    ///
+    /// \param used_states the number of states used (after
+    /// renumbering)
     void defrag_states(std::vector<unsigned>&& newst, unsigned used_states)
     {
       SPOT_ASSERT(newst.size() >= states_.size());

spot/twa/twagraph.hh

@@ -1,5 +1,5 @@
 // -*- coding: utf-8 -*-
-// Copyright (C) 2014-2020 Laboratoire de Recherche et Développement
+// Copyright (C) 2014-2021 Laboratoire de Recherche et Développement
 // de l'Epita.
 //
 // This file is part of Spot, a model checking library.
@@ -554,7 +554,7 @@ namespace spot
     ///
     /// In the first pass, edges that share their source, destination,
     /// and acceptance marks are merged into a single edge whose condition
-    /// is the conjunction of the conditions of the original edges.
+    /// is the disjunction of the conditions of the original edges.
     ///
     /// In the second pass, which is performed only on automata with
     /// Fin-less acceptance, edges with the same source, destination,
@@ -695,12 +695,20 @@ namespace spot
     /// digraph::defrag_state() that additionally deals with universal
     /// branching.
     ///
+    /// This method is used to remove some states that have been
+    /// previously detected to be unreachable in order to "defragment"
+    /// the state vector.  When a state is removed, all its outgoing
+    /// transition are removed as well.  Removing reachable states
+    /// should NOT be attempted, because the incoming edges will be
+    /// dangling.
+    ///
     /// \param newst A vector indicating how each state should be
-    /// renumbered.  Use -1U to erase a state.  Ignoring the
+    /// renumbered.  Use -1U to mark an unreachable state for removal.
-    /// occurrences of -1U, the renumbering is expected to
+    /// Ignoring the occurrences of -1U, the renumbering is expected
-    /// satisfy newst[i] ≤ i for all i.
+    /// to satisfy newst[i] ≤ i for all i.
-    /// \param used_states the number of states used
+    ///
-    /// (after renumbering)
+    /// \param used_states the number of states used after
+    /// renumbering.
     void defrag_states(std::vector<unsigned>&& newst, unsigned used_states);
 
     /// \brief Print the data structures used to represent the