* src/tgba/bddprint.hh (bdd_format_set): New function.

* src/tgba/bddprint.cc (bdd_format_set): Likewise.
* src/tgba/state.hh: Add Doxygen comments.
(state::compare): Take a state*, not a state&.
(state_ptr_less_than): New functor.
* src/tgba/statebdd.hh (state_bdd::compare): Take a state*, not a
state&.
* src/tgba/statebdd.cc (state_bdd::compare): Likewise.
* src/tgba/succiter.hh: Add Doxygen comments.
* src/tgba/tgba.hh: Mention promises.
(tgba::formate_state): New pure virtual method.
* src/tgba/tgbabddconcrete.hh (tgba_bdd_concrete::formate_state):
New method.
* src/tgba/tgbabddconcrete.cc (tgba_bdd_concrete::formate_state):
Likewise.
* src/tgbaalgos/dotty.cc: Adjust to use state_ptr_less_than
and tgba::formate_state.

src/tgba/succiter.hh

@@ -6,6 +6,13 @@
 namespace spot
 {
 
+  /// \brief Iterate over the successors of a state.
+  ///
+  /// This class provides the basic functionalities required to
+  /// iterate over the successors of a state, as well as querying
+  /// transition labels.  Because transitions are never explicitely
+  /// encoded, labels (conditions and promises) can only be queried
+  /// while iterating over the successors.
   class tgba_succ_iterator
   {
   public:
@@ -14,15 +21,57 @@ namespace spot
     {
     }
 
-    // iteration
+    /// \name Iteration
+    //@{
+
+    /// \brief Position the iterator on the first successor (if any).
+    ///
+    /// This method can be called several times to make multiple
+    /// passes over successors.  
+    ///
+    /// \warning One should always call \c done() to
+    /// ensure there is a successor, even after \c first().  A
+    /// common trap is to assume that there is at least one
+    /// successor: this is wrong.
     virtual void first() = 0;
+
+    /// \brief Jump to the next successor (if any).
+    ///
+    /// \warning Again, one should always call \c done() to ensure
+    /// there is a successor.
     virtual void next() = 0;
+
+    /// \brief Check whether the iteration is finished.
+    ///
+    /// This function should be called after any call to \c first()
+    /// or \c next() and before any enquiry about the current state.
+    ///
+    /// The usual way to do this is with a \c for loop.
+    /// \code
+    ///    for (s->first(); !s->done(); s->next())
+    ///      ...
+    /// \endcode
     virtual bool done() = 0;
 
-    // inspection
+    //@}
+
+    /// \name Inspection
+    //@{
+
+    /// \brief Get the state of the current successor.
+    ///
+    /// Note that the same state may occur at different points
+    /// in the iteration.  These actually correspond to the same
+    /// destination.  It just means there were several transitions,
+    /// with different conditions or promises, leading to the
+    /// same state.
     virtual state* current_state() = 0;
+    /// \brief Get the condition on the transition leading to this successor.
     virtual bdd current_condition() = 0;
+    /// \brief Get the promise on the transition leading to this successor.
     virtual bdd current_promise() = 0;
+
+    //@}
   };
 
 }