algo: covers: Add documenation to approximate enhanced covers

alib2algo/src/stringology/cover/ApproximateEnhancedCoversCommon.h

@@ -10,12 +10,19 @@ namespace stringology::cover {
 class ApproximateEnhancedCoversCommon {
 protected:
+	/**
+	 * A simple structure used to represent the element of d-subset corresponding
+	 * to a state q of a nondeterministic finite automaton.
+	 */
 	struct Element {
 		unsigned depth, level;
 		Element ( ) = default;
 		Element ( unsigned d, unsigned l ) : depth ( d ), level ( l ) { }
 	};
+	/**
+	 * State of the deterministic trie-like k-approximate suffix automaton.
+	 */
 	template < class SymbolType >
 	struct State {
 		unsigned							depth = 0;
@@ -23,12 +30,48 @@ protected:
 		ext::vector < Element >				elements;
 	};
+	/**
+	 * Computes the number of covered positions by the given state.
+	 *
+	 * @param q state of the deterministic k-approximate suffix automaton
+	 * @return the number of covered positions
+	 */
 	template < class SymbolType >
 	static unsigned distEnhCov ( State < SymbolType > const * q );
+
+	/**
+	 * Computes the number of covered positions by the given state and updates the
+	 * set of found (relaxed) k-approximate enhanced covers if necessary.
+	 *
+	 * @param state
+	 * @param enhCovers set of all (relaxed) k-approximate enhanced covers
+	 * @param h the maximum number of covered position
+	 */
 	template < class SymbolType >
 	static void updateEnhCov ( State < SymbolType > const * state, ext::set < string::LinearString < SymbolType > > & enhCovers, unsigned & h );
+
+	/**
+	 * Constructs the first state of deterministic k-approximate suffix automaton
+	 * obtained by reading symbol "symbol".
+	 *
+	 * @param x the original string
+	 * @param k the maximum number of allowed errors
+	 * @param symbol the first read symbol
+	 * @return the first state of deterministic k-approximate suffix automaton
+	 */
 	template < class SymbolType >
 	static State < SymbolType > * constrFirstState ( const string::LinearString < SymbolType > & x, unsigned k, const SymbolType & symbol );
+
+	/**
+	 * Constructs the next state of deterministic k-approximate suffix automaton
+	 * approachable by the previous state by reading the symbol "symbol".
+	 *
+	 * @param x the original string
+	 * @param previousState
+	 * @param k the maximum number of allowed errors
+	 * @param symbol read symbol
+	 * @return the next state of deterministic k-approximate suffix automaton
+	 */
 	template < class SymbolType >
 	static State < SymbolType > * constrNextState ( const string::LinearString < SymbolType > & x, State < SymbolType > const * previousState, unsigned k, const SymbolType & symbol );
 };

alib2algo/src/stringology/cover/ApproximateEnhancedCoversComputation.h

@@ -6,13 +6,32 @@
 #include <stringology/cover/ApproximateEnhancedCoversCommon.h>
 namespace stringology::cover {
-
+/**
+ * Computation of all k-approximate enhanced covers under Hamming distance.
+ */
 class ApproximateEnhancedCoversComputation : ApproximateEnhancedCoversCommon {
 public:
+	/**
+	 * Computes all k-approximate enhanced covers under Hamming distance.
+	 *
+	 * @param x the original string for which k-approximate enhanced covers are
+	 * computed
+	 * @param k the maximum number of allowed errors
+	 * @return set of all k-approximate enhanced covers under Hamming distance
+	 */
 	template < class SymbolType >
 	static ext::set < string::LinearString < SymbolType > > compute ( const string::LinearString < SymbolType > & x, unsigned k );
 private:
+	/**
+	 * Checks if a string represented by the state of the backbone of
+	 * k-approximate deterministic suffix automaton is a border.
+	 *
+	 * @param state
+	 * @param x the original string
+	 * @param k maximum number of allowed errors
+	 * @return true if state represents border, false otherwise
+	 */
 	template < class SymbolType >
 	static bool isBorder ( State < SymbolType > const * state, const string::LinearString < SymbolType > & x, unsigned k );
 };
@@ -24,13 +43,15 @@ ext::set < string::LinearString < SymbolType > > ApproximateEnhancedCoversComput
 	 // the maximum number of covered positions
 	unsigned h = 0;
+	 // there are no borders for an empty string and a string with only one
+	 // character
 	if ( x.getContent ( ).size ( ) < 2 )
 		return result;
 	State < SymbolType > * previousState = constrFirstState ( x, k, x.getContent ( )[0] );
 	State < SymbolType > * nextState = nullptr;
-	 // check if the the first character is a border (makes sense only for k = 0)
+	 // check if the first character is a border (makes sense only for k = 0)
 	if ( isBorder ( previousState, x, k ) )
 		updateEnhCov ( previousState, result, h );