Doxygen comments.

* src/ta/ta.cc, src/ta/ta.hh, src/ta/taexplicit.hh,
src/ta/taproduct.cc, src/ta/taproduct.hh, src/ta/tgbtaexplicit.cc,
src/ta/taexplicit.cc, src/ta/tgbtaproduct.cc,
src/taalgos/emptinessta.cc, src/taalgos/emptinessta.hh,
src/taalgos/tgba2ta.cc, src/taalgos/tgba2ta.hh,
src/tgbatest/ltl2ta.test, src/tgbatest/ltl2tgba.cc: Add Doxygen
comments.

src/taalgos/emptinessta.hh

@@ -36,11 +36,54 @@ namespace spot
 
   namespace
   {
-    typedef std::pair<spot::state*, ta_succ_iterator*> pair_state_iter;
+    typedef std::pair<spot::state*, ta_succ_iterator_product*> pair_state_iter;
   }
-  /// \brief An implementation of the ta emptiness-check algorithm.
+
+  /// \addtogroup emptiness_check Emptiness-checks
+  /// \ingroup ta_algorithms
   ///
-  /// See the documentation for spot::ta.
+  /// \brief Check whether the language of a product between a Kripke structure
+  ///  and a TA is empty. It works for both standard and generalized form of TA.
+  ///
+  /// you should call \c check to check the product automaton.
+  /// If \c check() returns false, then the product automaton
+  /// was found empty.  Otherwise the automaton accepts some run.
+  ///
+  /// This is based on the following paper.
+  /// \verbatim
+  ///  @InProceedings{        geldenhuys.06.spin,
+  ///  author        = {Jaco Geldenhuys and Henri Hansen},
+  ///  title         = {Larger Automata and Less Work for {LTL} Model Checking},
+  ///  booktitle     = {Proceedings of the 13th International SPIN Workshop
+  ///                  (SPIN'06)},
+  ///  year          = {2006},
+  ///  pages         = {53--70},
+  ///  series        = {Lecture Notes in Computer Science},
+  ///  volume        = {3925},
+  ///  publisher     = {Springer}
+  /// }
+  /// \endverbatim
+  ///
+  /// the implementation of \c check is inspired from the two-pass algorithm
+  /// of the paper above:
+  /// - the fist-pass detect all Buchi-accepting cycles and includes
+  //  the heuristic proposed in the paper to detect some
+  /// livelock-accepting cycles.
+  /// - the second-pass detect all livelock-accepting cycles.
+  /// In addition, we add some optimizations to the fist pass:
+  /// 1- Detection of all (livelock-accepting) cycles containing a least
+  /// one state that is both livelock and accepting states
+  /// 2- Detection of all livelock-accepting cycles containing a least
+  /// one state (k,t) such as its "TA component" t is a livelock-accepting
+  /// state that has no successors in the TA automaton.
+  ///
+  /// The implementation of each pass is a SCC-based algorithm inspired
+  /// from spot::gtec.hh.
+
+  /// \brief An implementation of the emptiness-check algorithm for a product
+  /// between a TA and a Kripke structure
+  ///
+  /// See the paper cited above.
   class ta_check : public ec_statistics
   {
   public:
@@ -48,26 +91,38 @@ namespace spot
     virtual
     ~ta_check();
 
-    /// Check whether the automaton's language is empty.
+    /// \brief Check whether the TA product automaton contains an accepting run:
+    /// it detects the two kinds of accepting runs: Buchi-accepting runs
+    /// and livelock-accepting runs. This emptiness check algorithm can also
+    /// check a product using the generalized form of TA.
+    ///
+    /// Return false if the product automaton accepts no run, otherwise true
+    ///
+    /// \param disable_second_pass: is used to disable the second pass when
+    /// when it is not necessary, for example when all the livelock-accepting
+    /// states of the TA automaton have no successors, we call this kind of
+    /// TA as STA (Single-pass Testing Automata)
+    /// (see spot::tgba2ta::add_artificial_livelock_accepting_state() for an
+    /// automatic transformation of any TA automaton into STA automaton
+    ///
+    /// \param disable_heuristic_for_livelock_detection: disable the heuristic
+    /// used in the first pass to detect livelock-accepting runs,
+    /// this heuristic is described in the paper cited above
     virtual bool
-    check(bool disable_second_pass = false);
+    check(bool disable_second_pass = false,
+        bool disable_heuristic_for_livelock_detection = false);
 
+    /// \brief Check whether the product automaton contains
+    /// a livelock-accepting run
+    /// Return false if the product automaton accepts no livelock-accepting run,
+    /// otherwise true
     virtual bool
-    livelock_detection(const ta* t);
+    livelock_detection(const ta_product* t);
 
+    /// Print statistics, if any.
     virtual std::ostream&
     print_stats(std::ostream& os) const;
 
-    /// \brief Return the status of the emptiness-check.
-    ///
-    /// When check() succeed, the status should be passed along
-    /// to spot::counter_example.
-    ///
-    /// This status should not be deleted, it is a pointer
-    /// to a member of this class that will be deleted when
-    /// the ta object is deleted.
-    //  const tgba_check_status* result() const;
-
   protected:
     void
     clear(numbered_state_heap* h, std::stack<pair_state_iter> todo, std::queue<
@@ -77,19 +132,23 @@ namespace spot
     clear(numbered_state_heap* h, std::stack<pair_state_iter> todo,
         spot::ta_succ_iterator* init_states_it);
 
+    /// the heuristic for livelock-accepting runs detection, it's described
+    /// in the paper cited above
     bool
     heuristic_livelock_detection(const state * stuttering_succ,
         numbered_state_heap* h, int h_livelock_root, std::set<const state*,
             state_ptr_less_than> liveset_curr);
+
     const ta_product* a_; ///< The automaton.
     option_map o_; ///< The options
 
+    // Force the second pass
     bool is_full_2_pass_;
 
-    // * scc: a stack of strongly connected components (SCC)
+    // scc: a stack of strongly connected components (SCC)
     scc_stack_ta scc;
 
-    // * sscc: a stack of strongly stuttering-connected components (SSCC)
+    // sscc: a stack of strongly stuttering-connected components (SSCC)
     scc_stack_ta sscc;
 
   };