* src/tgba/succiter.hh (tgba_succ_iterator::current_state):

Return a state*, not a state_bdd.
* src/tgba/succiterconcrete.hh
(tgba_succ_iterator_concrete::current_state): Return a state_bdd*,
not a state_bdd.
* src/tgba/state.hh (state::as_bdd): New abstract method.
* src/tgba/statebdd.hh (state_bdd::as_bdd): Move definitions ...
* src/tgba/statebdd.cc (state_bdd::as_bdd): ... here.
* src/tgba/tgba.hh: Add Doxygen comments.
(tgba::succ_iter, tgba::get_init_state): Use state*, not state_bdd.
* src/tgba/tgbabddconcrete.hh (tgba_bdd_concrete::get_init_state):
Return a state_bdd*, not a state_bdd.
(tgba_bdd_concrete::get_init_bdd): New method.
(tgba_bdd_concrete::succ_uter): Take a state* as argument.
* src/tgba/tgbabddconcrete.cc: Likewise.
* src/tgba/tgbabddtranslatefactory.cc
(tgba_bdd_translate_factory::tgba_bdd_translate_factory): Use
tgba_bdd_concrete::get_init_bdd.
* src/tgbaalgos/dotty.cc (dotty_state, dotty_rec, dotty): Adjust
to use state* instead of state_bdd.
* src/tgba/succlist.hh: Delete.  (Leftover from a previous
draft.)

src/tgba/tgba.hh

@@ -1,12 +1,34 @@
 #ifndef SPOT_TGBA_TGBA_HH
 # define SPOT_TGBA_TGBA_HH
 
-#include "statebdd.hh"
+#include "state.hh"
 #include "succiter.hh"
 #include "tgbabdddict.hh"
 
 namespace spot
 {
+  /// \brief A Transition-based Generalized Büchi Automaton.
+  ///
+  /// The acronym TGBA (Transition-based Generalized Büchi Automaton)
+  /// was coined by Dimitra Giannakopoulou and Flavio Lerda
+  /// in "From States to Transitions: Improving Translation of LTL
+  /// Formulae to Büchi Automata".  (FORTE'02)
+  ///
+  /// TGBAs are transition-based, meanings their labels are put
+  /// on arcs, not on nodes.  They use Generalized Büchi acceptance
+  /// conditions: there are several accepting sets (of
+  /// transitions), and a path can be accepted only if it traverse
+  /// at least one transition of each set infinitely often.
+  ///
+  /// Browsing such automaton can be achieved using two functions.
+  /// \c get_init_state, and \c succ_iter.  The former returns
+  /// the initial state while the latter allows to explore the
+  /// successor states of any state.
+  ///
+  /// Note that although this is a transition-based automata,
+  /// we never represent transitions!  Transition informations are
+  /// obtained by querying the iterator over the successors of
+  /// a state.
   class tgba
   {
   public:
@@ -15,9 +37,33 @@ namespace spot
     {
     }
 
-    virtual state_bdd get_init_state() const = 0;
-    virtual tgba_succ_iterator* succ_iter(state_bdd state) const = 0;
+    /// \brief Get the initial state of the automaton.
+    ///
+    /// The state has been allocated with \c new.  It is the
+    /// responsability of the caller to \c delete it when no
+    /// longer needed.
+    virtual state* get_init_state() const = 0;
 
+    /// \brief Get an iterator over the successors of \a state.
+    ///
+    /// The iterator has been allocated with \c new.  It is the
+    /// responsability of the caller to \c delete it when no
+    /// longer needed.
+    ///
+    /// \param state is the state whose successors are to be explored.
+    /// This pointer is not adopted in any way by \c succ_iter, and
+    /// it is still the caller's responsability to delete it when
+    /// appropriate (this can be done during the lifetime of
+    /// the iterator).
+    virtual tgba_succ_iterator* succ_iter(const state* state) const = 0;
+
+    /// \brief Get the dictionary associated to the automaton.
+    ///
+    /// State are represented as BDDs.  The dictionary allows
+    /// to map BDD variables back to formulae, and vice versa.
+    /// This is useful when dealing with several automata (which
+    /// may use the same BDD variable for different formula),
+    /// or simply when printing.
     virtual const tgba_bdd_dict& get_dict() const = 0;
   };