From e8977ccd6dc1e2ce4b0c3e970f7c4b689197ea26 Mon Sep 17 00:00:00 2001
From: Jan Travnicek <Jan.Travnicek@fit.cvut.cz>
Date: Fri, 8 Feb 2019 14:41:50 +0100
Subject: [PATCH] user documentation of regexp conversion algos
---
alib2algo/src/regexp/convert/ToAutomaton.h | 4 ++--
.../src/regexp/convert/ToAutomatonDerivation.cpp | 13 +++++++++++--
.../src/regexp/convert/ToAutomatonDerivation.h | 10 ++++++++--
.../src/regexp/convert/ToAutomatonGlushkov.cpp | 13 +++++++++++--
alib2algo/src/regexp/convert/ToAutomatonGlushkov.h | 10 +++++++---
.../src/regexp/convert/ToAutomatonThompson.cpp | 13 +++++++++++--
alib2algo/src/regexp/convert/ToAutomatonThompson.h | 14 +++++++++++---
alib2algo/src/regexp/convert/ToGrammar.cpp | 13 +++++++++++--
alib2algo/src/regexp/convert/ToGrammar.h | 13 +++++++++----
.../regexp/convert/ToGrammarRightRGDerivation.cpp | 13 +++++++++++--
.../regexp/convert/ToGrammarRightRGDerivation.h | 12 +++++++++---
.../regexp/convert/ToGrammarRightRGGlushkov.cpp | 13 +++++++++++--
.../src/regexp/convert/ToGrammarRightRGGlushkov.h | 10 +++++-----
13 files changed, 117 insertions(+), 34 deletions(-)
diff --git a/alib2algo/src/regexp/convert/ToAutomaton.h b/alib2algo/src/regexp/convert/ToAutomaton.h
index 8de21c9723..81fc6903b7 100644
--- a/alib2algo/src/regexp/convert/ToAutomaton.h
+++ b/alib2algo/src/regexp/convert/ToAutomaton.h
@@ -33,7 +33,7 @@ public:
*
* \param regexp the regular expression
*
- * \return finite automaotn equivalent to original regular expression.
+ * \return finite automaotn equivalent to original regular expression
*/
template < class SymbolType >
static automaton::NFA < SymbolType, ext::pair < SymbolType, unsigned > > convert ( const regexp::FormalRegExp < SymbolType > & regexp );
@@ -45,7 +45,7 @@ public:
*
* \param regexp the regular expression
*
- * \return finite automaotn equivalent to original regular expression.
+ * \return finite automaotn equivalent to original regular expression
*/
template < class SymbolType >
static automaton::NFA < SymbolType, ext::pair < SymbolType, unsigned > > convert ( const regexp::UnboundedRegExp < SymbolType > & regexp );
diff --git a/alib2algo/src/regexp/convert/ToAutomatonDerivation.cpp b/alib2algo/src/regexp/convert/ToAutomatonDerivation.cpp
index 7feb5ae6db..774a2b6b16 100644
--- a/alib2algo/src/regexp/convert/ToAutomatonDerivation.cpp
+++ b/alib2algo/src/regexp/convert/ToAutomatonDerivation.cpp
@@ -12,8 +12,17 @@ namespace regexp {
namespace convert {
-auto ToAutomatonDerivationFormalRegExp = registration::AbstractRegister < ToAutomatonDerivation, automaton::DFA < DefaultSymbolType, unsigned >, const regexp::FormalRegExp < > & > ( ToAutomatonDerivation::convert );
-auto ToAutomatonDerivationUnboundedRegExp = registration::AbstractRegister < ToAutomatonDerivation, automaton::DFA < DefaultSymbolType, unsigned >, const regexp::UnboundedRegExp < > & > ( ToAutomatonDerivation::convert );
+auto ToAutomatonDerivationFormalRegExp = registration::AbstractRegister < ToAutomatonDerivation, automaton::DFA < DefaultSymbolType, unsigned >, const regexp::FormalRegExp < > & > ( ToAutomatonDerivation::convert ).setDocumentation (
+"Implements conversion of regular expressions to finite automata usign Brzozowski's derivation algorithm.\n\
+\n\
+@param regexp the regexp to convert\n\
+@return finite automaton accepting the language described by the original regular expression" );
+
+auto ToAutomatonDerivationUnboundedRegExp = registration::AbstractRegister < ToAutomatonDerivation, automaton::DFA < DefaultSymbolType, unsigned >, const regexp::UnboundedRegExp < > & > ( ToAutomatonDerivation::convert, "regexp" ).setDocumentation (
+"Implements conversion of regular expressions to finite automata usign Brzozowski's derivation algorithm.\n\
+\n\
+@param regexp the regexp to convert\n\
+@return finite automaton accepting the language described by the original regular expression" );
} /* namespace convert */
diff --git a/alib2algo/src/regexp/convert/ToAutomatonDerivation.h b/alib2algo/src/regexp/convert/ToAutomatonDerivation.h
index b0b53a9c3d..191f465230 100644
--- a/alib2algo/src/regexp/convert/ToAutomatonDerivation.h
+++ b/alib2algo/src/regexp/convert/ToAutomatonDerivation.h
@@ -34,8 +34,14 @@ namespace convert {
class ToAutomatonDerivation {
public:
/**
- * Performs conversion.
- * @return FSM equivalent to original regular expression.
+ * Implements conversion of regular expressions to finite automata usign Brzozowski's derivation algorithm.
+ *
+ * \tparam T the type of regular expression to convert
+ * \tparam SymbolType the type of symbols in the regular expression
+ *
+ * \param regexp the regexp to convert
+ *
+ * \return finite automaton accepting the language described by the original regular expression
*/
template < class T, class SymbolType = typename T::symbol_type >
static automaton::DFA < SymbolType, unsigned > convert ( const T & regexp );
diff --git a/alib2algo/src/regexp/convert/ToAutomatonGlushkov.cpp b/alib2algo/src/regexp/convert/ToAutomatonGlushkov.cpp
index 8e8b4d6b28..5ec6b8a8d1 100644
--- a/alib2algo/src/regexp/convert/ToAutomatonGlushkov.cpp
+++ b/alib2algo/src/regexp/convert/ToAutomatonGlushkov.cpp
@@ -12,8 +12,17 @@ namespace regexp {
namespace convert {
-auto ToAutomatonGlushkovUnboundedRegExp = registration::AbstractRegister < ToAutomatonGlushkov, automaton::NFA < DefaultSymbolType, ext::pair < DefaultSymbolType, unsigned > >, const regexp::UnboundedRegExp < > & > ( ToAutomatonGlushkov::convert );
-auto ToAutomatonGlushkovFormalRegExp = registration::AbstractRegister < ToAutomatonGlushkov, automaton::NFA < DefaultSymbolType, ext::pair < DefaultSymbolType, unsigned > >, const regexp::FormalRegExp < > & > ( ToAutomatonGlushkov::convert );
+auto ToAutomatonGlushkovUnboundedRegExp = registration::AbstractRegister < ToAutomatonGlushkov, automaton::NFA < DefaultSymbolType, ext::pair < DefaultSymbolType, unsigned > >, const regexp::UnboundedRegExp < > & > ( ToAutomatonGlushkov::convert, "regexp" ).setDocumentation (
+"Implements conversion of regular expressions to finite automata usign Glushkov's method of neighbours.\n\
+\n\
+@param regexp the regexp to convert\n\
+@return finite automaton accepting the language described by the original regular expression" );
+
+auto ToAutomatonGlushkovFormalRegExp = registration::AbstractRegister < ToAutomatonGlushkov, automaton::NFA < DefaultSymbolType, ext::pair < DefaultSymbolType, unsigned > >, const regexp::FormalRegExp < > & > ( ToAutomatonGlushkov::convert, "regexp" ).setDocumentation (
+"Implements conversion of regular expressions to finite automata usign Glushkov's method of neighbours.\n\
+\n\
+@param regexp the regexp to convert\n\
+@return finite automaton accepting the language described by the original regular expression" );
} /* namespace convert */
diff --git a/alib2algo/src/regexp/convert/ToAutomatonGlushkov.h b/alib2algo/src/regexp/convert/ToAutomatonGlushkov.h
index a7444ba28a..fb68149322 100644
--- a/alib2algo/src/regexp/convert/ToAutomatonGlushkov.h
+++ b/alib2algo/src/regexp/convert/ToAutomatonGlushkov.h
@@ -38,9 +38,13 @@ namespace convert {
class ToAutomatonGlushkov {
public:
/**
- * Performs conversion.
- * @param re Original regular expression.
- * @return NFA equivalent to original regular expression.
+ * Implements conversion of regular expressions to finite automata usign Glushkov's method of neighbours.
+ *
+ * \tparam SymbolType the type of symbols in the regular expression
+ *
+ * \param regexp the regexp to convert
+ *
+ * \return finite automaton accepting the language described by the original regular expression
*/
template < class SymbolType >
static automaton::NFA < SymbolType, ext::pair < SymbolType, unsigned > > convert ( const regexp::UnboundedRegExp < SymbolType > & regexp );
diff --git a/alib2algo/src/regexp/convert/ToAutomatonThompson.cpp b/alib2algo/src/regexp/convert/ToAutomatonThompson.cpp
index d9b50f26dc..63663685d5 100644
--- a/alib2algo/src/regexp/convert/ToAutomatonThompson.cpp
+++ b/alib2algo/src/regexp/convert/ToAutomatonThompson.cpp
@@ -51,8 +51,17 @@ automaton::EpsilonNFA < > ToAutomatonThompson::convert(const regexp::UnboundedRe
return automaton;
}
-auto ToAutomatonThompsonFormalRegExp = registration::AbstractRegister < ToAutomatonThompson, automaton::EpsilonNFA < >, const regexp::FormalRegExp < > & > ( ToAutomatonThompson::convert );
-auto ToAutomatonThompsonUnboundedRegExp = registration::AbstractRegister < ToAutomatonThompson, automaton::EpsilonNFA < >, const regexp::UnboundedRegExp < > & > ( ToAutomatonThompson::convert );
+auto ToAutomatonThompsonFormalRegExp = registration::AbstractRegister < ToAutomatonThompson, automaton::EpsilonNFA < >, const regexp::FormalRegExp < > & > ( ToAutomatonThompson::convert, "regexp" ).setDocumentation (
+"Implements conversion of regular expressions to finite automata usign Thompson's method of incremental construction.\n\
+\n\
+@param regexp the regexp to convert\n\
+@return finite automaton accepting the language described by the original regular expression" );
+
+auto ToAutomatonThompsonUnboundedRegExp = registration::AbstractRegister < ToAutomatonThompson, automaton::EpsilonNFA < >, const regexp::UnboundedRegExp < > & > ( ToAutomatonThompson::convert, "regexp" ).setDocumentation (
+"Implements conversion of regular expressions to finite automata usign Thompson's method of incremental construction.\n\
+\n\
+@param regexp the regexp to convert\n\
+@return finite automaton accepting the language described by the original regular expression" );
// ----------------------------------------------------------------------------
diff --git a/alib2algo/src/regexp/convert/ToAutomatonThompson.h b/alib2algo/src/regexp/convert/ToAutomatonThompson.h
index c6973cd0c4..25acbfd7e4 100644
--- a/alib2algo/src/regexp/convert/ToAutomatonThompson.h
+++ b/alib2algo/src/regexp/convert/ToAutomatonThompson.h
@@ -29,11 +29,19 @@ namespace convert {
class ToAutomatonThompson {
public:
/**
- * Performs conversion.
- * @param regexp regexp to convert
- * @return nondeterministic finite automaton with epsilon transitions accepting language described by the regexp
+ * Implements conversion of regular expressions to finite automata usign Thompson's method of incremental construction.
+ *
+ * \tparam SymbolType the type of symbols in the regular expression
+ *
+ * \param regexp the regexp to convert
+ *
+ * \return finite automaton accepting the language described by the original regular expression
*/
static automaton::EpsilonNFA < > convert(const regexp::FormalRegExp < > & regexp);
+
+ /**
+ * \overload
+ */
static automaton::EpsilonNFA < > convert(const regexp::UnboundedRegExp < > & regexp);
class Unbounded {
diff --git a/alib2algo/src/regexp/convert/ToGrammar.cpp b/alib2algo/src/regexp/convert/ToGrammar.cpp
index 0bb63c7a90..40919d2338 100644
--- a/alib2algo/src/regexp/convert/ToGrammar.cpp
+++ b/alib2algo/src/regexp/convert/ToGrammar.cpp
@@ -12,8 +12,17 @@ namespace regexp {
namespace convert {
-auto ToGrammarFormalRegExp = registration::AbstractRegister < ToGrammar, grammar::RightRG < DefaultSymbolType, ext::pair < DefaultSymbolType, unsigned > >, const regexp::FormalRegExp < > & > ( ToGrammar::convert );
-auto ToGrammarUnboundedRegExp = registration::AbstractRegister < ToGrammar, grammar::RightRG < DefaultSymbolType, ext::pair < DefaultSymbolType, unsigned > >, const regexp::UnboundedRegExp < > & > ( ToGrammar::convert );
+auto ToGrammarFormalRegExp = registration::AbstractRegister < ToGrammar, grammar::RightRG < DefaultSymbolType, ext::pair < DefaultSymbolType, unsigned > >, const regexp::FormalRegExp < > & > ( ToGrammar::convert, "regexp" ).setDocumentation (
+"Converts the regular expression into a grammar (@sa regexp::convert::ToGrammarRightRGGlushkov::convert).\n\
+\n\
+@param regexp the regular expression\n\
+@return right regular grammar equivalent to original regular expression" );
+
+auto ToGrammarUnboundedRegExp = registration::AbstractRegister < ToGrammar, grammar::RightRG < DefaultSymbolType, ext::pair < DefaultSymbolType, unsigned > >, const regexp::UnboundedRegExp < > & > ( ToGrammar::convert, "regexp" ).setDocumentation (
+"Converts the regular expression into a grammar (@sa regexp::convert::ToGrammarRightRGGlushkov::convert).\n\
+\n\
+@param regexp the regular expression\n\
+@return right regular grammar equivalent to original regular expression" );
} /* namespace convert */
diff --git a/alib2algo/src/regexp/convert/ToGrammar.h b/alib2algo/src/regexp/convert/ToGrammar.h
index c4f386c235..dba255164d 100644
--- a/alib2algo/src/regexp/convert/ToGrammar.h
+++ b/alib2algo/src/regexp/convert/ToGrammar.h
@@ -14,16 +14,21 @@ namespace regexp {
namespace convert {
+/**
+ * Conversion of regular expression to regular grammar.
+ * This class serves as a "default wrapper" over the conversion of RE to RG. It delegates to the glushkov conversion algorithm.
+ * @sa regexp::convert::ToGrammarRightRGGlushkov
+ */
class ToGrammar {
public:
/**
- * Performs conversion.
+ * Converts the regular expression into a grammar (@sa regexp::convert::ToGrammarRightRGGlushkov::convert).
*
- * \tparam SymbolType type of symbols in the regexp
+ * \tparam SymbolType the type of regular expression
*
- * \param regexp the converted regexp
+ * \param regexp the regular expression
*
- * \return right regular grammar equivalent to source regexp.
+ * \return right regular grammar equivalent to original regular expression.
*/
template < class SymbolType >
static grammar::RightRG < SymbolType, ext::pair < SymbolType, unsigned > > convert(const regexp::FormalRegExp < SymbolType > & regexp);
diff --git a/alib2algo/src/regexp/convert/ToGrammarRightRGDerivation.cpp b/alib2algo/src/regexp/convert/ToGrammarRightRGDerivation.cpp
index b6f2df7a1a..c0dadd865f 100644
--- a/alib2algo/src/regexp/convert/ToGrammarRightRGDerivation.cpp
+++ b/alib2algo/src/regexp/convert/ToGrammarRightRGDerivation.cpp
@@ -12,8 +12,17 @@ namespace regexp {
namespace convert {
-auto ToGrammarRightRGDerivationUnboundedRegExp = registration::AbstractRegister < ToGrammarRightRGDerivation, grammar::RightRG < DefaultSymbolType, unsigned >, const regexp::UnboundedRegExp < > & > ( ToGrammarRightRGDerivation::convert );
-auto ToGrammarRightRGDerivationFormalRegExp = registration::AbstractRegister < ToGrammarRightRGDerivation, grammar::RightRG < DefaultSymbolType, unsigned >, const regexp::FormalRegExp < > & > ( ToGrammarRightRGDerivation::convert );
+auto ToGrammarRightRGDerivationUnboundedRegExp = registration::AbstractRegister < ToGrammarRightRGDerivation, grammar::RightRG < DefaultSymbolType, unsigned >, const regexp::UnboundedRegExp < > & > ( ToGrammarRightRGDerivation::convert, "regexp" ).setDocumentation (
+"Implements conversion of regular expressions to regular grammars usign Brzozowski's derivation algorithm.\n\
+\n\
+@param regexp the regexp to convert\n\
+@return right regular grammar generating the language described by the original regular expression" );
+
+auto ToGrammarRightRGDerivationFormalRegExp = registration::AbstractRegister < ToGrammarRightRGDerivation, grammar::RightRG < DefaultSymbolType, unsigned >, const regexp::FormalRegExp < > & > ( ToGrammarRightRGDerivation::convert, "regexp" ).setDocumentation (
+"Implements conversion of regular expressions to regular grammars usign Brzozowski's derivation algorithm.\n\
+\n\
+@param regexp the regexp to convert\n\
+@return right regular grammar generating the language described by the original regular expression" );
} /* namespace convert */
diff --git a/alib2algo/src/regexp/convert/ToGrammarRightRGDerivation.h b/alib2algo/src/regexp/convert/ToGrammarRightRGDerivation.h
index 2791abadf9..3f31331bbe 100644
--- a/alib2algo/src/regexp/convert/ToGrammarRightRGDerivation.h
+++ b/alib2algo/src/regexp/convert/ToGrammarRightRGDerivation.h
@@ -29,14 +29,20 @@ namespace regexp {
namespace convert {
/**
- * Converts reg. expression to right regular grammar using brzozowski derivation algorithm.
+ * Converts regular expression to right regular grammar using Brzozowski's derivation algorithm.
* Source: Melichar 2.137
*/
class ToGrammarRightRGDerivation {
public:
/**
- * Performs conversion.
- * @return right regular grammar equivalent to source regexp.
+ * Implements conversion of regular expressions to regular grammars usign Brzozowski's derivation algorithm.
+ *
+ * \tparam T the type of regular expression to convert
+ * \tparam SymbolType the type of symbols in the regular expression
+ *
+ * \param regexp the regexp to convert
+ *
+ * \return right regular grammar generating the language described by the original regular expression
*/
template < class T, class SymbolType = typename regexp::SymbolTypeOfRegexp < T > >
static grammar::RightRG < SymbolType, unsigned > convert ( const T & regexp );
diff --git a/alib2algo/src/regexp/convert/ToGrammarRightRGGlushkov.cpp b/alib2algo/src/regexp/convert/ToGrammarRightRGGlushkov.cpp
index ee9e2abcda..2350319c39 100644
--- a/alib2algo/src/regexp/convert/ToGrammarRightRGGlushkov.cpp
+++ b/alib2algo/src/regexp/convert/ToGrammarRightRGGlushkov.cpp
@@ -12,8 +12,17 @@ namespace regexp {
namespace convert {
-auto ToGrammarRightRGGlushkovUnboundedRegExp = registration::AbstractRegister < ToGrammarRightRGGlushkov, grammar::RightRG < DefaultSymbolType, ext::pair < DefaultSymbolType, unsigned > >, const regexp::UnboundedRegExp < > & > ( ToGrammarRightRGGlushkov::convert );
-auto ToGrammarRightRGGlushkovFormalRegExp = registration::AbstractRegister < ToGrammarRightRGGlushkov, grammar::RightRG < DefaultSymbolType, ext::pair < DefaultSymbolType, unsigned > >, const regexp::FormalRegExp < > & > ( ToGrammarRightRGGlushkov::convert );
+auto ToGrammarRightRGGlushkovUnboundedRegExp = registration::AbstractRegister < ToGrammarRightRGGlushkov, grammar::RightRG < DefaultSymbolType, ext::pair < DefaultSymbolType, unsigned > >, const regexp::UnboundedRegExp < > & > ( ToGrammarRightRGGlushkov::convert, "regexp" ).setDocumentation (
+"Implements conversion of regular expressions to finite automata usign Glushkov's method of neighbours.\n\
+\n\
+@param regexp the regexp to convert\n\
+@return right regular grammar generating the language described by the original regular expression" );
+
+auto ToGrammarRightRGGlushkovFormalRegExp = registration::AbstractRegister < ToGrammarRightRGGlushkov, grammar::RightRG < DefaultSymbolType, ext::pair < DefaultSymbolType, unsigned > >, const regexp::FormalRegExp < > & > ( ToGrammarRightRGGlushkov::convert, "regexp" ).setDocumentation (
+"Implements conversion of regular expressions to finite automata usign Glushkov's method of neighbours.\n\
+\n\
+@param regexp the regexp to convert\n\
+@return right regular grammar generating the language described by the original regular expression" );
} /* namespace convert */
diff --git a/alib2algo/src/regexp/convert/ToGrammarRightRGGlushkov.h b/alib2algo/src/regexp/convert/ToGrammarRightRGGlushkov.h
index d6588235a1..7bf32eedeb 100644
--- a/alib2algo/src/regexp/convert/ToGrammarRightRGGlushkov.h
+++ b/alib2algo/src/regexp/convert/ToGrammarRightRGGlushkov.h
@@ -28,19 +28,19 @@ namespace regexp {
namespace convert {
/**
- * Converts regular expression to right regular grammar using Glushkov algorithm.
+ * Converts regular expression to right regular grammar using Glushkov algorithm of neighbours.
* Source: None yet.
*/
class ToGrammarRightRGGlushkov {
public:
/**
- * Performs conversion.
+ * Implements conversion of regular expressions to finite automata usign Glushkov's method of neighbours.
*
- * \tparam SymbolType tye of symbols in the regular expression
+ * \tparam SymbolType the type of symbols in the regular expression
*
- * \param regexp original regular expression
+ * \param regexp the regexp to convert
*
- * \return right regular grammar equivalent to source regexp.
+ * \return right regular grammar generating the language described by the original regular expression
*/
template < class SymbolType >
static grammar::RightRG < SymbolType, ext::pair < SymbolType, unsigned > > convert(const regexp::FormalRegExp < SymbolType > & regexp);
--
GitLab