From 1e694b088d2fab425a20b6798cd9a252e51aa32f Mon Sep 17 00:00:00 2001
From: Jan Travnicek <Jan.Travnicek@fit.cvut.cz>
Date: Mon, 4 Feb 2019 13:03:29 +0100
Subject: [PATCH] add user documentation to grammar convert
---
alib2algo/src/grammar/convert/ToAutomaton.cpp | 27 ++++++++++++--
alib2algo/src/grammar/convert/ToAutomaton.h | 37 ++++++++++++++++---
.../grammar/convert/ToAutomatonBottomUp.cpp | 13 ++++++-
.../src/grammar/convert/ToAutomatonBottomUp.h | 10 ++++-
.../src/grammar/convert/ToGrammarLeftRG.cpp | 6 ++-
.../src/grammar/convert/ToGrammarLeftRG.h | 4 +-
.../src/grammar/convert/ToGrammarRightRG.cpp | 6 ++-
.../src/grammar/convert/ToGrammarRightRG.h | 4 +-
alib2algo/src/grammar/convert/ToRegExp.cpp | 13 ++++++-
alib2algo/src/grammar/convert/ToRegExp.h | 7 +++-
.../src/grammar/convert/ToRegExpAlgebraic.cpp | 13 ++++++-
.../src/grammar/convert/ToRegExpAlgebraic.h | 4 +-
12 files changed, 119 insertions(+), 25 deletions(-)
diff --git a/alib2algo/src/grammar/convert/ToAutomaton.cpp b/alib2algo/src/grammar/convert/ToAutomaton.cpp
index 80de0d939f..03d43851d5 100644
--- a/alib2algo/src/grammar/convert/ToAutomaton.cpp
+++ b/alib2algo/src/grammar/convert/ToAutomaton.cpp
@@ -11,10 +11,29 @@ namespace grammar {
namespace convert {
-auto ToAutomatonLeftRG = registration::AbstractRegister < ToAutomaton, automaton::NFA < >, const grammar::LeftRG < > & > ( ToAutomaton::convert );
-auto ToAutomatonRightRG = registration::AbstractRegister < ToAutomaton, automaton::NFA < >, const grammar::RightRG < > & > ( ToAutomaton::convert );
-auto ToAutomatonCFG = registration::AbstractRegister < ToAutomaton, automaton::NPDA < DefaultSymbolType, DefaultEpsilonType, ext::variant < DefaultSymbolType, DefaultSymbolType >, unsigned >, const grammar::CFG < > & > ( ToAutomaton::convert );
-auto ToAutomatonEpsilonFreeCFG = registration::AbstractRegister < ToAutomaton, automaton::NPDA < DefaultSymbolType, DefaultEpsilonType, ext::variant < DefaultSymbolType, DefaultSymbolType >, unsigned >, const grammar::EpsilonFreeCFG < > & > ( ToAutomaton::convert );
+auto ToAutomatonLeftRG = registration::AbstractRegister < ToAutomaton, automaton::NFA < >, const grammar::LeftRG < > & > ( ToAutomaton::convert, "grammar" ).setDocumentation (
+"Performs the conversion.\n\
+\n\
+@param grammar the left regular grammar to convert\n\
+@return finite automaton accepting the language generated by @p grammar" );
+
+auto ToAutomatonRightRG = registration::AbstractRegister < ToAutomaton, automaton::NFA < >, const grammar::RightRG < > & > ( ToAutomaton::convert, "grammar" ).setDocumentation (
+"Performs the conversion.\n\
+\n\
+@param grammar the left regular grammar to convert\n\
+@return finite automaton accepting the language generated by @p grammar" );
+
+auto ToAutomatonCFG = registration::AbstractRegister < ToAutomaton, automaton::NPDA < DefaultSymbolType, DefaultEpsilonType, ext::variant < DefaultSymbolType, DefaultSymbolType >, unsigned >, const grammar::CFG < > & > ( ToAutomaton::convert, "grammar" ).setDocumentation (
+"Performs the conversion.\n\
+\n\
+@param grammar some context free grammar\n\
+@return pushdown automaton accepting the language generated by @p grammar" );
+
+auto ToAutomatonEpsilonFreeCFG = registration::AbstractRegister < ToAutomaton, automaton::NPDA < DefaultSymbolType, DefaultEpsilonType, ext::variant < DefaultSymbolType, DefaultSymbolType >, unsigned >, const grammar::EpsilonFreeCFG < > & > ( ToAutomaton::convert, "grammar" ).setDocumentation (
+"Performs the conversion.\n\
+\n\
+@param grammar some context free grammar\n\
+@return pushdown automaton accepting the language generated by @p grammar" );
} /* namespace convert */
diff --git a/alib2algo/src/grammar/convert/ToAutomaton.h b/alib2algo/src/grammar/convert/ToAutomaton.h
index ee9c818337..c61e9f50a2 100644
--- a/alib2algo/src/grammar/convert/ToAutomaton.h
+++ b/alib2algo/src/grammar/convert/ToAutomaton.h
@@ -33,15 +33,42 @@ namespace convert {
class ToAutomaton {
public:
/**
- * Performs conversion.
- * @param grammar Regular grammar to convert.
- * @return FSM equivalent to source grammar.
+ * Performs the conversion.
+ *
+ * \tparam TerminalSymbolType the type of terminal symbol of the grammar
+ * \tparam NonterminalSymbolType the type of nonterminal symbol of the grammar
+ *
+ * \param grammar the left regular grammar to convert.
+ *
+ * \return finite automaton accepting the language generated by @p grammar.
*/
template < class TerminalSymbolType, class NonterminalSymbolType >
- static automaton::NFA < TerminalSymbolType, NonterminalSymbolType > convert(const grammar::LeftRG < TerminalSymbolType, NonterminalSymbolType > & grammar);
+ static automaton::NFA < TerminalSymbolType, NonterminalSymbolType > convert ( const grammar::LeftRG < TerminalSymbolType, NonterminalSymbolType > & grammar );
+
+ /**
+ * \overload
+ *
+ * \tparam TerminalSymbolType the type of terminal symbol of the grammar
+ * \tparam NonterminalSymbolType the type of nonterminal symbol of the grammar
+ *
+ * \param grammar the right regular grammar to convert.
+ *
+ * \return finite automaton accepting the language generated by @p grammar.
+ */
template < class TerminalSymbolType, class NonterminalSymbolType >
- static automaton::NFA < TerminalSymbolType, NonterminalSymbolType > convert(const grammar::RightRG < TerminalSymbolType, NonterminalSymbolType > & grammar);
+ static automaton::NFA < TerminalSymbolType, NonterminalSymbolType > convert ( const grammar::RightRG < TerminalSymbolType, NonterminalSymbolType > & grammar );
+ /**
+ * \overload
+ *
+ * \tparam T the type of converted grammar
+ * \tparam TerminalSymbolType the type of terminal symbol of the grammar
+ * \tparam NonterminalSymbolType the type of nonterminal symbol of the grammar
+ *
+ * \param grammar some context free grammar.
+ *
+ * \return pushdown automaton accepting the language generated by @p grammar.
+ */
template < class T, class TerminalSymbolType = typename grammar::TerminalSymbolTypeOfGrammar < T >, class NonterminalSymbolType = typename grammar::NonterminalSymbolTypeOfGrammar < T > >
static automaton::NPDA < TerminalSymbolType, DefaultEpsilonType, ext::variant < TerminalSymbolType, NonterminalSymbolType >, unsigned > convert ( const T & grammar );
};
diff --git a/alib2algo/src/grammar/convert/ToAutomatonBottomUp.cpp b/alib2algo/src/grammar/convert/ToAutomatonBottomUp.cpp
index a74aff1100..478383bdfa 100644
--- a/alib2algo/src/grammar/convert/ToAutomatonBottomUp.cpp
+++ b/alib2algo/src/grammar/convert/ToAutomatonBottomUp.cpp
@@ -11,8 +11,17 @@ namespace grammar {
namespace convert {
-auto ToAutomatonBottomUpCFG = registration::AbstractRegister < ToAutomatonBottomUp, automaton::NPDA < DefaultSymbolType, DefaultEpsilonType, ext::variant < DefaultSymbolType, DefaultSymbolType >, unsigned >, const grammar::CFG < > & > ( ToAutomatonBottomUp::convert );
-auto ToAutomatonBottomUpEpsilonFreeCFG = registration::AbstractRegister < ToAutomatonBottomUp, automaton::NPDA < DefaultSymbolType, DefaultEpsilonType, ext::variant < DefaultSymbolType, DefaultSymbolType >, unsigned >, const grammar::EpsilonFreeCFG < > & > ( ToAutomatonBottomUp::convert );
+auto ToAutomatonBottomUpCFG = registration::AbstractRegister < ToAutomatonBottomUp, automaton::NPDA < DefaultSymbolType, DefaultEpsilonType, ext::variant < DefaultSymbolType, DefaultSymbolType >, unsigned >, const grammar::CFG < > & > ( ToAutomatonBottomUp::convert, "grammar" ).setDocumentation (
+"Converts a context free grammar to a pushdown automaton by method of bottom up analysis.\n\
+\n\
+@param grammar the converted context free grammar\n\
+@return pushdown automaton accepting the language generated by @p grammar");
+
+auto ToAutomatonBottomUpEpsilonFreeCFG = registration::AbstractRegister < ToAutomatonBottomUp, automaton::NPDA < DefaultSymbolType, DefaultEpsilonType, ext::variant < DefaultSymbolType, DefaultSymbolType >, unsigned >, const grammar::EpsilonFreeCFG < > & > ( ToAutomatonBottomUp::convert, "grammar" ).setDocumentation (
+"Converts a context free grammar to a pushdown automaton by method of bottom up analysis.\n\
+\n\
+@param grammar the converted context free grammar\n\
+@return pushdown automaton accepting the language generated by @p grammar");
} /* namespace convert */
diff --git a/alib2algo/src/grammar/convert/ToAutomatonBottomUp.h b/alib2algo/src/grammar/convert/ToAutomatonBottomUp.h
index c82649bdbf..473bfb606a 100644
--- a/alib2algo/src/grammar/convert/ToAutomatonBottomUp.h
+++ b/alib2algo/src/grammar/convert/ToAutomatonBottomUp.h
@@ -28,7 +28,15 @@ namespace convert {
class ToAutomatonBottomUp {
public:
/**
- * Performs conversion.
+ * Converts a context free grammar to a pushdown automaton by method of bottom up analysis.
+ *
+ * \tparam T the type of converted grammar
+ * \tparam TerminalSymbolType the type of terminals in the converted grammar
+ * \tparam NonterminalSymbolType the type of nonterminals in the converted grammar
+ *
+ * \param grammar the converted context free grammar
+ *
+ * \return pushdown automaton accepting the language generated by @p grammar
*/
template < class T, class TerminalSymbolType = typename grammar::TerminalSymbolTypeOfGrammar < T >, class NonterminalSymbolType = typename grammar::NonterminalSymbolTypeOfGrammar < T > >
static automaton::NPDA < TerminalSymbolType, DefaultEpsilonType, ext::variant < TerminalSymbolType, NonterminalSymbolType >, unsigned > convert(const T& grammar);
diff --git a/alib2algo/src/grammar/convert/ToGrammarLeftRG.cpp b/alib2algo/src/grammar/convert/ToGrammarLeftRG.cpp
index f91cb42a56..1028f62ba6 100644
--- a/alib2algo/src/grammar/convert/ToGrammarLeftRG.cpp
+++ b/alib2algo/src/grammar/convert/ToGrammarLeftRG.cpp
@@ -12,7 +12,11 @@ namespace grammar {
namespace convert {
-auto ToGrammarLeftRGRightRG = registration::AbstractRegister < ToGrammarLeftRG, grammar::LeftRG < >, const grammar::RightRG < > & > ( ToGrammarLeftRG::convert );
+auto ToGrammarLeftRGRightRG = registration::AbstractRegister < ToGrammarLeftRG, grammar::LeftRG < >, const grammar::RightRG < > & > ( ToGrammarLeftRG::convert, "grammar" ).setDocumentation (
+"Transforms a right regular grammar to left regular grammar.\n\
+\n\
+@param grammar the right regular grammar to convert\n\
+@return left regular grammar which is equivalent to source right regular grammar." );
} /* namespace convert */
diff --git a/alib2algo/src/grammar/convert/ToGrammarLeftRG.h b/alib2algo/src/grammar/convert/ToGrammarLeftRG.h
index 8fe5e86b7a..190e758413 100644
--- a/alib2algo/src/grammar/convert/ToGrammarLeftRG.h
+++ b/alib2algo/src/grammar/convert/ToGrammarLeftRG.h
@@ -23,12 +23,12 @@ namespace convert {
class ToGrammarLeftRG {
public:
/**
- * Performs conversion.
+ * Transforms a right regular grammar to left regular grammar.
*
* \tparam TerminalSymbolType used for the terminal alphabet of the grammar.
* \tparam NonterminalSymbolType used for the nonterminal alphabet, and the initial symbol of the grammar.
*
- * \param grammar Right regular grammar to convert
+ * \param grammar the right regular grammar to convert
*
* \return left regular grammar which is equivalent to source right regular grammar.
*/
diff --git a/alib2algo/src/grammar/convert/ToGrammarRightRG.cpp b/alib2algo/src/grammar/convert/ToGrammarRightRG.cpp
index a906b00f7a..cab9d33e21 100644
--- a/alib2algo/src/grammar/convert/ToGrammarRightRG.cpp
+++ b/alib2algo/src/grammar/convert/ToGrammarRightRG.cpp
@@ -12,7 +12,11 @@ namespace grammar {
namespace convert {
-auto ToGrammarRightRGLeftRG = registration::AbstractRegister < ToGrammarRightRG, grammar::RightRG < >, const grammar::LeftRG < > & > ( ToGrammarRightRG::convert );
+auto ToGrammarRightRGLeftRG = registration::AbstractRegister < ToGrammarRightRG, grammar::RightRG < >, const grammar::LeftRG < > & > ( ToGrammarRightRG::convert, "grammar" ).setDocumentation (
+"Transforms a left regular grammar to right regular grammar.\n\
+\n\
+@param grammar the left regular grammar to convert\n\
+@return right regular grammar which is equivalent to source left regular grammar." );
} /* namespace convert */
diff --git a/alib2algo/src/grammar/convert/ToGrammarRightRG.h b/alib2algo/src/grammar/convert/ToGrammarRightRG.h
index b22ba5bece..144f139304 100644
--- a/alib2algo/src/grammar/convert/ToGrammarRightRG.h
+++ b/alib2algo/src/grammar/convert/ToGrammarRightRG.h
@@ -23,12 +23,12 @@ namespace convert {
class ToGrammarRightRG {
public:
/**
- * Performs conversion.
+ * Transforms a left regular grammar to right regular grammar.
*
* \tparam TerminalSymbolType used for the terminal alphabet of the grammar.
* \tparam NonterminalSymbolType used for the nonterminal alphabet, and the initial symbol of the grammar.
*
- * \param grammar Left regular grammar to convert
+ * \param grammar left regular grammar to convert
*
* \return right regular grammar which is equivalent to source left regular grammar.
*/
diff --git a/alib2algo/src/grammar/convert/ToRegExp.cpp b/alib2algo/src/grammar/convert/ToRegExp.cpp
index f78e6bc305..2d678b1dfe 100644
--- a/alib2algo/src/grammar/convert/ToRegExp.cpp
+++ b/alib2algo/src/grammar/convert/ToRegExp.cpp
@@ -12,8 +12,17 @@ namespace grammar {
namespace convert {
-auto ToRegExpRightRG = registration::AbstractRegister < ToRegExp, regexp::UnboundedRegExp < >, const grammar::RightRG < > & > ( ToRegExp::convert );
-auto ToRegExpLeftRG = registration::AbstractRegister < ToRegExp, regexp::UnboundedRegExp < >, const grammar::LeftRG < > & > ( ToRegExp::convert );
+auto ToRegExpRightRG = registration::AbstractRegister < ToRegExp, regexp::UnboundedRegExp < >, const grammar::RightRG < > & > ( ToRegExp::convert, "grammar" ).setDocumentation (
+"Converts a regular grammar to regular expression.\n\
+\n\
+@param grammar the regular grammar to convert\n\
+@return regexp describing language generated by @p grammar." );
+
+auto ToRegExpLeftRG = registration::AbstractRegister < ToRegExp, regexp::UnboundedRegExp < >, const grammar::LeftRG < > & > ( ToRegExp::convert, "grammar" ).setDocumentation (
+"Converts a regular grammar to regular expression.\n\
+\n\
+@param grammar the regular grammar to convert\n\
+@return regexp describing language generated by @p grammar." );
} /* namespace convert */
diff --git a/alib2algo/src/grammar/convert/ToRegExp.h b/alib2algo/src/grammar/convert/ToRegExp.h
index c3069c533e..b70678eb1e 100644
--- a/alib2algo/src/grammar/convert/ToRegExp.h
+++ b/alib2algo/src/grammar/convert/ToRegExp.h
@@ -20,8 +20,11 @@ namespace convert {
class ToRegExp {
public:
/**
- * \param grammar Grammar to convert
- * \return regexp equivalent to source right regular grammar.
+ * Converts a regular grammar to regular expression.
+ *
+ * \param grammar the regular grammar to convert
+ *
+ * \return regexp describing language generated by @p grammar.
*/
template < class TerminalSymbolType, class NonterminalSymbolType >
static regexp::UnboundedRegExp < TerminalSymbolType > convert ( const grammar::RightRG < TerminalSymbolType, NonterminalSymbolType > & grammar );
diff --git a/alib2algo/src/grammar/convert/ToRegExpAlgebraic.cpp b/alib2algo/src/grammar/convert/ToRegExpAlgebraic.cpp
index 1aa50c530d..3c431de767 100644
--- a/alib2algo/src/grammar/convert/ToRegExpAlgebraic.cpp
+++ b/alib2algo/src/grammar/convert/ToRegExpAlgebraic.cpp
@@ -12,8 +12,17 @@ namespace grammar {
namespace convert {
-auto ToRegExpAlgebraicLeftRG = registration::AbstractRegister < ToRegExpAlgebraic, regexp::UnboundedRegExp < >, const grammar::LeftRG < > & > ( ToRegExpAlgebraic::convert );
-auto ToRegExpAlgebraicRightRG = registration::AbstractRegister < ToRegExpAlgebraic, regexp::UnboundedRegExp < >, const grammar::RightRG < > & > ( ToRegExpAlgebraic::convert );
+auto ToRegExpAlgebraicLeftRG = registration::AbstractRegister < ToRegExpAlgebraic, regexp::UnboundedRegExp < >, const grammar::LeftRG < > & > ( ToRegExpAlgebraic::convert, "grammar" ).setDocumentation (
+"Converts a regular grammar to regular expression using regular equations.\n\
+\n\
+@param grammar Grammar to convert\n\
+@return regexp describing language generated by the @p grammar" );
+
+auto ToRegExpAlgebraicRightRG = registration::AbstractRegister < ToRegExpAlgebraic, regexp::UnboundedRegExp < >, const grammar::RightRG < > & > ( ToRegExpAlgebraic::convert, "grammar" ).setDocumentation (
+"Converts a regular grammar to regular expression using regular equations.\n\
+\n\
+@param grammar Grammar to convert\n\
+@return regexp describing language generated by the @p grammar" );
} /* namespace convert */
diff --git a/alib2algo/src/grammar/convert/ToRegExpAlgebraic.h b/alib2algo/src/grammar/convert/ToRegExpAlgebraic.h
index 6bfdf0943c..418d48e422 100644
--- a/alib2algo/src/grammar/convert/ToRegExpAlgebraic.h
+++ b/alib2algo/src/grammar/convert/ToRegExpAlgebraic.h
@@ -24,8 +24,10 @@ namespace convert {
class ToRegExpAlgebraic {
public:
/**
- * @return regexp equivalent to source right regular grammar.
+ * Converts a regular grammar to regular expression using regular equations.
+ *
* @param grammar Grammar to convert
+ * @return regexp describing language generated by the @p grammar
*/
template < class TerminalSymbolType, class NonterminalSymbolType >
static regexp::UnboundedRegExp < TerminalSymbolType > convert ( const grammar::RightRG < TerminalSymbolType, NonterminalSymbolType > & grammar);
--
GitLab