From 1dbb5f7c58074b1f7f6f7f4cfc31b1709fb1ac8c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20Tr=C3=A1vn=C3=AD=C4=8Dek?= <travnja3@fit.cvut.cz>
Date: Sat, 22 May 2021 12:03:01 +0200
Subject: [PATCH] data: update documentation of various TA

---
 alib2data/src/automaton/TA/DFTA.h          | 23 ++++++------
 alib2data/src/automaton/TA/EpsilonNFTA.h   | 41 +++++++++++-----------
 alib2data/src/automaton/TA/NFTA.h          | 23 ++++++------
 alib2data/src/automaton/TA/UnorderedDFTA.h | 31 ++++++++--------
 alib2data/src/automaton/TA/UnorderedNFTA.h | 27 +++++++-------
 5 files changed, 73 insertions(+), 72 deletions(-)

diff --git a/alib2data/src/automaton/TA/DFTA.h b/alib2data/src/automaton/TA/DFTA.h
index 8e40e59531..71830ff513 100644
--- a/alib2data/src/automaton/TA/DFTA.h
+++ b/alib2data/src/automaton/TA/DFTA.h
@@ -49,10 +49,11 @@ class FinalStates;
 
  * \details
  * Definition is classical definition of finite automata.
- * A = (Q, T, \delta, F),
+ * A = (Q, \Sigma, \delta, F),
  * Q (States) = nonempty finite set of states,
- * T (TerminalAlphabet) = finite set of terminal ranked symbols - having this empty won't let automaton do much though,
- * \delta = transition function of the form (A, B, C, ...) \times a -> X, where A, B, C, ..., X \in Q and a \in T,
+ * \Sigma (TerminalAlphabet) = finite set of terminal ranked symbols - having this empty won't let automaton do much though,
+ *  - the alphabet may be partitioned based on the arity of symbols into \Sigma_n, where n is the arity.
+ * \delta = transition function of the form (Q^n \times \Sigma_n) \mapsto Q,
  * F (FinalStates) = set of final states
  *
  * Elements of the \delta mapping must meet following criteria. The size of the state list must equal the rank of the ranked symbol.
@@ -251,11 +252,11 @@ public:
 	/**
 	 * \brief Add a transition to the automaton.
 	 *
-	 * \details The transition is in a form ( A, B, C, ... ) \times a -> X, where A, B, C, ..., X \in Q and a \in T
+	 * \details The transition is in a form (Q^n \times \Sigma_n) \mapsto Q,
 	 *
-	 * \param children the source states (A, B, C, ...)
-	 * \param current the input symbol (a)
-	 * \param next the target state (B)
+	 * \param children the source states in Q^n
+	 * \param current the input symbol in \Sigma_n
+	 * \param next the target state in Q
 	 *
 	 * \throws AutomatonException when transition contains state or symbol not present in the automaton components
 	 *
@@ -266,11 +267,11 @@ public:
 	/**
 	 * \brief Removes a transition from the automaton.
 	 *
-	 * \details The transition is in a form ( A, B, C, ... ) \times a -> X, where A, B, C, ..., X \in Q and a \in T
+	 * \details The transition is in a form (Q^n \times \Sigma_n) \mapsto Q,
 	 *
-	 * \param children the source states (A, B, C, ...)
-	 * \param current the input symbol (a)
-	 * \param next the target state (B)
+	 * \param children the source states in Q^n
+	 * \param current the input symbol in \Sigma_n
+	 * \param next the target state in Q
 	 *
 	 * \returns true if the transition was indeed removed
 	 */
diff --git a/alib2data/src/automaton/TA/EpsilonNFTA.h b/alib2data/src/automaton/TA/EpsilonNFTA.h
index f041911923..27d604dfea 100644
--- a/alib2data/src/automaton/TA/EpsilonNFTA.h
+++ b/alib2data/src/automaton/TA/EpsilonNFTA.h
@@ -53,10 +53,11 @@ class FinalStates;
 
  * \details
  * Definition is classical definition of epsilon finite tree automata.
- * A = (Q, T, \delta, F),
+ * A = (Q, \Sigma, \delta, F),
  * Q (States) = nonempty finite set of states,
- * T (TerminalAlphabet) = finite set of terminal ranked symbols - having this empty won't let automaton do much though,
- * \delta = transition function of the form ( (A, B, C, ...) \times a) \cup A \times \epsilon -> P(Q), where A, B, C, ... \in Q, a \in T, and P(Q) is a powerset of states,
+ * \Sigma (TerminalAlphabet) = finite set of terminal ranked symbols - having this empty won't let automaton do much though,
+ *  - the alphabet may be partitioned based on the arity of symbols into \Sigma_n, where n is the arity.
+ * \delta = transition function of the form (Q^n \times \Sigma_n) \cup (Q \times \{\epsilon\} \mapsto P(Q),
  * F (FinalStates) = set of final states
  *
  * Elements of the \delta multimapping must meet following criteria. The size of the state list must equal the rank of the ranked symbol from the non-epsilon transition.
@@ -264,8 +265,7 @@ public:
 	/**
 	 * \brief Add a transition to the automaton.
 	 *
-	 * \details The transition is either in a form ( A, B, C, ... ) \times a -> X, where A, B, C, ..., X \in Q and a \in T
-	 *                                   or a form A \times \epsilon -> B, where A, B \in Q
+	 * \details The transition is in a form (Q^n \times \Sigma_n) \cup (Q \times \{\epsilon\}) \mapsto Q,
 	 *
 	 * \param lhs the left hand side of the transitions
 	 * \param rhs the right hand side of the transitions
@@ -279,11 +279,11 @@ public:
 	/**
 	 * \brief Add a transition to the automaton.
 	 *
-	 * \details The transition is in a form ( A, B, C, ... ) \times a -> X, where A, B, C, ..., X \in Q and a \in T
+	 * \details The transition is in a form (Q^n \times \Sigma_n) \mapsto Q,
 	 *
-	 * \param symbol the input symbol (a)
-	 * \param prevStates the source states (A, B, C, ...)
-	 * \param next the target state (B)
+	 * \param symbol the input symbol in \Sigma_n
+	 * \param prevStates the source states \in Q^n
+	 * \param next the target state \in Q
 	 *
 	 * \throws AutomatonException when transition contains state or symbol not present in the automaton components
 	 *
@@ -294,10 +294,10 @@ public:
 	/**
 	 * \brief Add a transition to the automaton.
 	 *
-	 * \details The transition is in a form A \times \epsilon -> B, where A, B \in Q
+	 * \details The transition is in a form Q \times \epsilon -> Q
 	 *
-	 * \param from the source state (A)
-	 * \param to the target state (B)
+	 * \param from the source state in Q
+	 * \param to the target state in Q
 	 *
 	 * \throws AutomatonException when transition contains state or symbol not present in the automaton components
 	 *
@@ -308,8 +308,7 @@ public:
 	/**
 	 * \brief Removes a transition from the automaton.
 	 *
-	 * \details The transition is either in a form ( A, B, C, ... ) \times a -> X, where A, B, C, ..., X \in Q and a \in T
-	 *                                   or a form A \times \epsilon -> B, where A, B \in Q
+	 * \details The transition is in a form (Q^n \times \Sigma_n) \cup (Q \times \{\epsilon\}) \mapsto Q,
 	 *
 	 * \param lhs the left hand side of the transitions
 	 * \param rhs the right hand side of the transitions
@@ -321,11 +320,11 @@ public:
 	/**
 	 * \brief Removes a transition from the automaton.
 	 *
-	 * \details The transition is in a form ( A, B, C, ... ) \times a -> X, where A, B, C, ..., X \in Q and a \in T
+	 * \details The transition is in a form (Q^n \times \Sigma_n) \mapsto Q,
 	 *
-	 * \param symbol the input symbol (a)
-	 * \param prevStates the source states (A, B, C, ...)
-	 * \param next the target state (B)
+	 * \param symbol the input symbol in \Sigma_n
+	 * \param prevStates the source states \in Q^n
+	 * \param next the target state \in Q
 	 *
 	 * \returns true if the transition was indeed removed
 	 */
@@ -334,10 +333,10 @@ public:
 	/**
 	 * \brief Removes a transition from the automaton.
 	 *
-	 * \details The transition is in a form A \times \epsilon -> B, where A, B \in Q
+	 * \details The transition is in a form Q \times \epsilon -> Q
 	 *
-	 * \param from the source state (A)
-	 * \param to the target state (B)
+	 * \param from the source state in Q
+	 * \param to the target state in Q
 	 *
 	 * \returns true if the transition was indeed removed
 	 */
diff --git a/alib2data/src/automaton/TA/NFTA.h b/alib2data/src/automaton/TA/NFTA.h
index 8aa4b006dc..0db6c5b2aa 100644
--- a/alib2data/src/automaton/TA/NFTA.h
+++ b/alib2data/src/automaton/TA/NFTA.h
@@ -52,10 +52,11 @@ class FinalStates;
 
  * \details
  * Definition is classical definition of finite automata.
- * A = (Q, T, \delta, F),
+ * A = (Q, \Sigma, \delta, F),
  * Q (States) = nonempty finite set of states,
- * T (TerminalAlphabet) = finite set of terminal ranked symbols - having this empty won't let automaton do much though,
- * \delta = transition function of the form (A, B, C, ...) \times a -> P(Q), where A, B, C, ... \in Q, a \in T, and P(Q) is a powerset of states,
+ * \Sigma (TerminalAlphabet) = finite set of terminal ranked symbols - having this empty won't let automaton do much though,
+ *  - the alphabet may be partitioned based on the arity of symbols into \Sigma_n, where n is the arity.
+ * \delta = transition function of the form (Q^n \times \Sigma_n) \mapsto P(Q),
  * F (FinalStates) = set of final states
  *
  * Elements of the \delta multimapping must meet following criteria. The size of the state list must equal the rank of the ranked symbol.
@@ -256,11 +257,11 @@ public:
 	/**
 	 * \brief Add a transition to the automaton.
 	 *
-	 * \details The transition is in a form ( A, B, C, ... ) \times a -> X, where A, B, C, ..., X \in Q and a \in T
+	 * \details The transition is in a form (Q^n \times \Sigma_n) \mapsto Q,
 	 *
-	 * \param children the source states (A, B, C, ...)
-	 * \param current the input symbol (a)
-	 * \param next the target state (B)
+	 * \param children the source states in Q^n
+	 * \param current the input symbol in \Sigma_n
+	 * \param next the target state in Q
 	 *
 	 * \throws AutomatonException when transition contains state or symbol not present in the automaton components
 	 *
@@ -271,11 +272,11 @@ public:
 	/**
 	 * \brief Removes a transition from the automaton.
 	 *
-	 * \details The transition is in a form ( A, B, C, ... ) \times a -> X, where A, B, C, ..., X \in Q and a \in T
+	 * \details The transition is in a form (Q^n \times \Sigma_n) \mapsto Q,
 	 *
-	 * \param children the source states (A, B, C, ...)
-	 * \param current the input symbol (a)
-	 * \param next the target state (B)
+	 * \param children the source states in Q^n
+	 * \param current the input symbol in \Sigma_n
+	 * \param next the target state in Q
 	 *
 	 * \returns true if the transition was indeed removed
 	 */
diff --git a/alib2data/src/automaton/TA/UnorderedDFTA.h b/alib2data/src/automaton/TA/UnorderedDFTA.h
index 99cb7d170a..35004044ef 100644
--- a/alib2data/src/automaton/TA/UnorderedDFTA.h
+++ b/alib2data/src/automaton/TA/UnorderedDFTA.h
@@ -45,14 +45,15 @@ class FinalStates;
 
 /**
  * \brief
- * Nondeterministic finite tree automaton without epsilon transitions. Accepts regular tree languages.
-
+ * Deterministic unordered finite tree automaton without epsilon transitions. Accepts regular tree languages.
+ *
  * \details
- * Definition is classical definition of finite automata.
- * A = (Q, T, \delta, F),
+ * Definition is similar to classical definition of finite automata.
+ * A = (Q, \Sigma, \delta, F),
  * Q (States) = nonempty finite set of states,
- * T (TerminalAlphabet) = finite set of terminal ranked symbols - having this empty won't let automaton do much though,
- * \delta = transition function of the form (A, B, C, ...) \times a -> X, where A, B, C, ..., X \in Q and a \in T,
+ * \Sigma (TerminalAlphabet) = finite set of terminal ranked symbols - having this empty won't let automaton do much though,
+ *  - the alphabet may be partitioned based on the arity of symbols into \Sigma_n, where n is the arity.
+ * \delta = transition function of the form \cup^n(Q) \times \Sigma_n -> Q, where \cup^n(Q) is a multiset of states,
  * F (FinalStates) = set of final states
  *
  * Elements of the \delta mapping must meet following criteria. The size of the state list must equal the rank of the ranked symbol.
@@ -60,8 +61,6 @@ class FinalStates;
  * Note that target state of a transition is required.
  * This class is used to store minimal, total, ... variants of deterministic finite tree automata.
  *
- * Elements of the \delta mapping must meet following criteria. The size of the state list must equal the rank of the ranked symbol.
- *
  * \tparam SymbolTypeT used for the symbol part of the ranked symbol
  * \tparam StateTypeT used to the states, and the initial state of the automaton.
  */
@@ -251,11 +250,11 @@ public:
 	/**
 	 * \brief Add a transition to the automaton.
 	 *
-	 * \details The transition is in a form ( A, B, C, ... ) \times a -> X, where A, B, C, ..., X \in Q and a \in T
+	 * \details The transition is in a form \cup^n(Q) \times \Sigma_n -> Q, where \cup^n(Q) is a multiset of states and P(Q) is a powerset of states,
 	 *
-	 * \param children the source states (A, B, C, ...)
-	 * \param current the input symbol (a)
-	 * \param next the target state (B)
+	 * \param children the source states in \cup^n(Q)
+	 * \param current the input symbol in \Sigma_n
+	 * \param next the target state in Q
 	 *
 	 * \throws AutomatonException when transition contains state or symbol not present in the automaton components
 	 *
@@ -266,11 +265,11 @@ public:
 	/**
 	 * \brief Removes a transition from the automaton.
 	 *
-	 * \details The transition is in a form ( A, B, C, ... ) \times a -> X, where A, B, C, ..., X \in Q and a \in T
+	 * \details The transition is in a form \cup^n(Q) \times \Sigma_n -> Q, where \cup^n(Q) is a multiset of states and P(Q) is a powerset of states,
 	 *
-	 * \param children the source states (A, B, C, ...)
-	 * \param current the input symbol (a)
-	 * \param next the target state (B)
+	 * \param children the source states in \cup^n(Q)
+	 * \param current the input symbol in \Sigma_n
+	 * \param next the target state in Q
 	 *
 	 * \returns true if the transition was indeed removed
 	 */
diff --git a/alib2data/src/automaton/TA/UnorderedNFTA.h b/alib2data/src/automaton/TA/UnorderedNFTA.h
index f52abd65d3..ca08261150 100644
--- a/alib2data/src/automaton/TA/UnorderedNFTA.h
+++ b/alib2data/src/automaton/TA/UnorderedNFTA.h
@@ -48,14 +48,15 @@ class FinalStates;
 
 /**
  * \brief
- * Nondeterministic finite tree automaton without epsilon transitions. Accepts regular tree languages.
+ * Nondeterministic unordered finite tree automaton without epsilon transitions. Accepts regular tree languages.
 
  * \details
- * Definition is classical definition of finite automata.
- * A = (Q, T, \delta, F),
+ * Definition is similar to classical definition of finite automata.
+ * A = (Q, \Sigma, \delta, F),
  * Q (States) = nonempty finite set of states,
- * T (TerminalAlphabet) = finite set of terminal ranked symbols - having this empty won't let automaton do much though,
- * \delta = transition function of the form (A, B, C, ...) \times a -> P(Q), where A, B, C, ... \in Q, a \in T, and P(Q) is a powerset of states,
+ * \Sigma (TerminalAlphabet) = finite set of terminal ranked symbols - having this empty won't let automaton do much though,
+ *  - the alphabet may be partitioned based on the arity of symbols into \Sigma_n, where n is the arity.
+ * \delta = transition function of the form \cup^n(Q) \times \Sigma_n -> P(Q), where \cup^n(Q) is a multiset of states and P(Q) is a powerset of states,
  * F (FinalStates) = set of final states
  *
  * Elements of the \delta multimapping must meet following criteria. The size of the state list must equal the rank of the ranked symbol.
@@ -256,11 +257,11 @@ public:
 	/**
 	 * \brief Add a transition to the automaton.
 	 *
-	 * \details The transition is in a form ( A, B, C, ... ) \times a -> X, where A, B, C, ..., X \in Q and a \in T
+	 * \details The transition is in a form \cup^n(Q) \times \Sigma_n -> P(Q), where \cup^n(Q) is a multiset of states and P(Q) is a powerset of states,
 	 *
-	 * \param children the source states (A, B, C, ...)
-	 * \param current the input symbol (a)
-	 * \param next the target state (B)
+	 * \param children the source states in \cup^n(Q)
+	 * \param current the input symbol in \Sigma_n
+	 * \param next the target state in Q
 	 *
 	 * \throws AutomatonException when transition contains state or symbol not present in the automaton components
 	 *
@@ -271,11 +272,11 @@ public:
 	/**
 	 * \brief Removes a transition from the automaton.
 	 *
-	 * \details The transition is in a form ( A, B, C, ... ) \times a -> X, where A, B, C, ..., X \in Q and a \in T
+	 * \details The transition is in a form \cup^n(Q) \times \Sigma_n -> P(Q), where \cup^n(Q) is a multiset of states and P(Q) is a powerset of states,
 	 *
-	 * \param children the source states (A, B, C, ...)
-	 * \param current the input symbol (a)
-	 * \param next the target state (B)
+	 * \param children the source states in \cup^n(Q)
+	 * \param current the input symbol in \Sigma_n
+	 * \param next the target state in Q
 	 *
 	 * \returns true if the transition was indeed removed
 	 */
-- 
GitLab