From d7156427f3d9c087bfc343700737e3ddc0dd36ce Mon Sep 17 00:00:00 2001
From: Jan Travnicek <Jan.Travnicek@fit.cvut.cz>
Date: Wed, 21 Mar 2018 11:26:44 +0100
Subject: [PATCH] continue documentation of trees

---
 alib2data/src/tree/ranked/PostfixRankedTree.h |   3 +-
 .../src/tree/ranked/PrefixRankedBarPattern.h  | 321 +++++++++++++++++-
 .../src/tree/ranked/PrefixRankedBarTree.h     | 242 ++++++++++++-
 alib2data/src/tree/ranked/PrefixRankedTree.h  |   3 +-
 alib2data/src/tree/ranked/RankedTree.h        |   3 +-
 5 files changed, 541 insertions(+), 31 deletions(-)

diff --git a/alib2data/src/tree/ranked/PostfixRankedTree.h b/alib2data/src/tree/ranked/PostfixRankedTree.h
index 5db703e9ea..541e00f6a7 100644
--- a/alib2data/src/tree/ranked/PostfixRankedTree.h
+++ b/alib2data/src/tree/ranked/PostfixRankedTree.h
@@ -366,7 +366,8 @@ namespace core {
 /**
  * Helper class specifying constraints for the tree's internal alphabet component.
  *
- * \tparam SymbolType used for the alphabet of the tree.
+ * \tparam SymbolType used for the symbol part of the ranked symbols of the alphabet of the pattern.
+ * \tparam RankType used for the rank part of the ranked symbols of the alphabet of the pattern.
  */
 template < class SymbolType, class RankType >
 class SetConstraint < ::tree::PostfixRankedTree < SymbolType, RankType >, common::ranked_symbol < SymbolType, RankType >, ::tree::GeneralAlphabet > {
diff --git a/alib2data/src/tree/ranked/PrefixRankedBarPattern.h b/alib2data/src/tree/ranked/PrefixRankedBarPattern.h
index f3ae758f06..1245864ef1 100644
--- a/alib2data/src/tree/ranked/PrefixRankedBarPattern.h
+++ b/alib2data/src/tree/ranked/PrefixRankedBarPattern.h
@@ -1,6 +1,22 @@
 /*
  * PrefixRankedBarPattern.h
  *
+ * This file is part of Algorithms library toolkit.
+ * Copyright (C) 2017 Jan Travnicek (jan.travnicek@fit.cvut.cz)
+
+ * Algorithms library toolkit is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+
+ * Algorithms library toolkit is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+
+ * You should have received a copy of the GNU General Public License
+ * along with Algorithms library toolkit.  If not, see <http://www.gnu.org/licenses/>.
+ *
  *  Created on: Nov 23, 2013
  *      Author: Jan Travnicek
  */
@@ -43,103 +59,273 @@ class BarSymbols;
 class VariablesBarSymbol;
 
 /**
- * Represents regular expression parsed from the XML. Regular expression is stored
- * as a tree of LinearStringElement.
+ * \brief
+ * Tree pattern represented as linear sequece as result of preorder traversal with additional bar symbols. The representation is so called ranked, therefore it consists of ranked symbols (bars are ranked as well). The rank of the ranked symbol need to compatible with unsigned integer. Additionally the pattern contains a special wildcard symbol representing any subtree. To match the wildcard, special bar symbol called variables bar is present as well.
+ *
+ * The bars represent end mark of all subpatterns in the notation.
+ *
+ * \details
+ * T = (A, B \subset A, C, W \in ( A \minus B ), Wb \in B ),
+ * A (Alphabet) = finite set of ranked symbols,
+ * B (Bars) = finite set of ranked symbols representing bars,
+ * C (Content) = linear representation of the pattern content
+ * W (Wildcard) = special symbol representing any subtree
+ * Wb (VariablesBar) = special bar symbol to match wildcard
+ *
+ * \tparam SymbolType used for the symbol part of the ranked symbol
+ * \tparam RankType used for the rank part of the ranked symbol
  */
 template < class SymbolType, class RankType >
 class PrefixRankedBarPattern final : public TreeBase, public core::Components < PrefixRankedBarPattern < SymbolType, RankType >, ext::set < common::ranked_symbol < SymbolType, RankType > >, component::Set, std::tuple < GeneralAlphabet, BarSymbols >, common::ranked_symbol < SymbolType, RankType >, component::Value, std::tuple < SubtreeWildcard, VariablesBarSymbol > > {
+	/**
+	 * Linear representation of the pattern content.
+	 */
 	ext::vector < common::ranked_symbol < SymbolType, RankType > > m_Data;
 
+	/**
+	 * Checker of validity of the representation of the ettern
+	 *
+	 * \throws TreeException when new pattern representation is not valid
+	 */
+	void arityChecksum ( const ext::vector < common::ranked_symbol < SymbolType, RankType > > & data );
+
 public:
+	/**
+	 * \brief Creates a new instance of the pattern with concrete alphabet, bars, content, wildcard, and variables bar.
+	 *
+	 * \param bars the initial bar set
+	 * \param variables bar the initial variables bar
+	 * \param subtreeWildcard the wildcard symbol
+	 * \param alphabet the initial alphabet of the pattern
+	 * \param data the initial pattern in linear representation
+	 */
 	explicit PrefixRankedBarPattern ( ext::set < common::ranked_symbol < SymbolType, RankType > > bar, common::ranked_symbol < SymbolType, RankType > variablesBar, common::ranked_symbol < SymbolType, RankType > subtreeWildcard, ext::set < common::ranked_symbol < SymbolType, RankType > > alphabet, ext::vector < common::ranked_symbol < SymbolType, RankType > > data );
+
+	/**
+	 * \brief Creates a new instance of the pattern with concrete bars, and content, wildcard and variables bar. The alphabet is deduced from the content.
+	 *
+	 * \param bars the initial bar set
+	 * \param variables bar the initial variables bar
+	 * \param subtreeWildcard the wildcard symbol
+	 * \param data the initial pattern in linear representation
+	 */
 	explicit PrefixRankedBarPattern ( ext::set < common::ranked_symbol < SymbolType, RankType > > bar, common::ranked_symbol < SymbolType, RankType > variablesBar, common::ranked_symbol < SymbolType, RankType > subtreeWildcard, ext::vector < common::ranked_symbol < SymbolType, RankType > > data );
+
+	/**
+	 * \brief Creates a new instance of the pattern based on the RankedPattern. The linear representation is constructed (including bars) by preorder traversal on the tree parameter. Bars and variables bar are provided as parameters.
+	 *
+	 * \param tree RankedTree representation of a tree.
+	 */
 	explicit PrefixRankedBarPattern ( SymbolType barBase, common::ranked_symbol < SymbolType, RankType > variablesBar, const RankedPattern < SymbolType, RankType > & tree );
+
+	/**
+	 * \brief Creates a new instance of the pattern based on the PrefixRankedBarTree. The linear representation is copied from tree. Bars and alphabet as well. Variables bar and subtree wildcard are defaultly constructed.
+	 *
+	 * \param tree RankedTree representation of a tree.
+	 */
 	explicit PrefixRankedBarPattern ( const PrefixRankedBarTree < SymbolType, RankType > & tree );
+
+	/**
+	 * \brief Creates a new instance of the pattern based on the RankedPattern. The linear representation is constructed (including bars) by preorder traversal on the tree parameter. Bars are computed to match symbols used in the representation from RankedPattern and variables bar is defaultly constructed.
+	 *
+	 * \param tree RankedTree representation of a tree.
+	 */
 	explicit PrefixRankedBarPattern ( const RankedPattern < SymbolType, RankType > & tree );
 
-	virtual TreeBase * clone ( ) const;
-	virtual TreeBase * plunder ( ) &&;
+	/**
+	 * @copydoc tree::TreeBase::clone()
+	 */
+	virtual TreeBase * clone ( ) const override;
+
+	/**
+	 * @copydoc tree::TreeBase::plunder()
+	 */
+	virtual TreeBase * plunder ( ) && override;
 
+	/**
+	 * Getter of the alphabet.
+	 *
+	 * \returns the alphabet of the pattern
+	 */
 	const ext::set < common::ranked_symbol < SymbolType, RankType > > & getAlphabet ( ) const & {
 		return this->template accessComponent < GeneralAlphabet > ( ).get ( );
 	}
 
+	/**
+	 * Getter of the alphabet.
+	 *
+	 * \returns the alphabet of the pattern
+	 */
 	ext::set < common::ranked_symbol < SymbolType, RankType > > && getAlphabet ( ) && {
 		return std::move ( this->template accessComponent < GeneralAlphabet > ( ).get ( ) );
 	}
 
+	/**
+	 * Adder of an alphabet symbols.
+	 *
+	 * \param symbols the new symbols to be added to the alphabet
+	 */
 	void extendAlphabet ( const ext::set < common::ranked_symbol < SymbolType, RankType > > & symbols ) {
 		this->template accessComponent < GeneralAlphabet > ( ).add ( symbols );
 	}
 
+	/**
+	 * Getter of the bar set.
+	 *
+	 * \returns the bar set of the pattern
+	 */
 	const ext::set < common::ranked_symbol < SymbolType, RankType > > & getBars ( ) const & {
 		return this->template accessComponent < BarSymbols > ( ).get ( );
 	}
 
+	/**
+	 * Getter of the bar set.
+	 *
+	 * \returns the bar set of the pattern
+	 */
 	ext::set < common::ranked_symbol < SymbolType, RankType > > && getBars ( ) && {
 		return std::move ( this->template accessComponent < BarSymbols > ( ).get ( ) );
 	}
 
+	/**
+	 * Adder of symbols to a bar set.
+	 *
+	 * \param symbols the new symbols to be added to the bar set
+	 */
 	void extendBars ( const ext::set < common::ranked_symbol < SymbolType, RankType > > & bars ) {
 		this->template accessComponent < BarSymbols > ( ).add ( bars );
 	}
 
+	/**
+	 * Getter of the wildcard symbol.
+	 *
+	 * \returns the wildcard symbol of the pattern
+	 */
 	const common::ranked_symbol < SymbolType, RankType > & getSubtreeWildcard ( ) const & {
 		return this->template accessComponent < SubtreeWildcard > ( ).get ( );
 	}
 
+	/**
+	 * Getter of the wildcard symbol.
+	 *
+	 * \returns the wildcard symbol of the pattern
+	 */
 	common::ranked_symbol < SymbolType, RankType > && getSubtreeWildcard ( ) && {
 		return std::move ( this->template accessComponent < SubtreeWildcard > ( ).get ( ) );
 	}
 
+	/**
+	 * Getter of the variables bar.
+	 *
+	 * \returns the variables bar of the pattern
+	 */
 	const common::ranked_symbol < SymbolType, RankType > & getVariablesBar ( ) const & {
 		return this->template accessComponent < VariablesBarSymbol > ( ).get ( );
 	}
 
+	/**
+	 * Getter of the variables bar.
+	 *
+	 * \returns the variables bar of the pattern
+	 */
 	common::ranked_symbol < SymbolType, RankType > && getVariablesBar ( ) && {
 		return std::move ( this->template accessComponent < VariablesBarSymbol > ( ).get ( ) );
 	}
 
 	/**
-	 * @return List of symbols forming tree (const version).
+	 * Getter of the pattern representation.
+	 *
+	 * \return List of symbols forming the linear representation of the pattern.
 	 */
 	const ext::vector < common::ranked_symbol < SymbolType, RankType > > & getContent ( ) const &;
 
+	/**
+	 * Getter of the pattern representation.
+	 *
+	 * \return List of symbols forming the linear representation of the pattern.
+	 */
 	ext::vector < common::ranked_symbol < SymbolType, RankType > > && getContent ( ) &&;
 
+	/**
+	 * Setter of the representation of the pattern.
+	 *
+	 * \throws TreeException when new pattern representation is not valid or when symbol of the representation are not present in the alphabet
+	 *
+	 * \param data new List of symbols forming the representation of the pattern.
+	 */
 	void setContent ( ext::vector < common::ranked_symbol < SymbolType, RankType > > data );
 
-	void arityChecksum ( const ext::vector < common::ranked_symbol < SymbolType, RankType > > & data );
-
 	/**
-	 * @return true if tree is an empty word (vector length is 0)
+	 * @return true if pattern is an empty word (vector length is 0). The method is present to allow compatibility with strings. Tree is never empty in this datatype.
 	 */
 	bool isEmpty ( ) const;
 
-	virtual int compare ( const ObjectBase & other ) const {
+	/**
+	 * @copydoc alib::CommonBase<ObjectBase>::compare ( const ObjectBase & )
+	 */
+	virtual int compare ( const ObjectBase & other ) const override {
 		if ( ext::type_index ( typeid ( * this ) ) == ext::type_index ( typeid ( other ) ) ) return this->compare ( ( decltype ( * this ) )other );
 
 		return ext::type_index ( typeid ( * this ) ) - ext::type_index ( typeid ( other ) );
 	}
 
-	virtual int compare ( const PrefixRankedBarPattern & other ) const;
+	/**
+	 * The actual compare method
+	 *
+	 * \param other the other instance
+	 *
+	 * \returns the actual relation between two by type same pattern instances
+	 */
+	int compare ( const PrefixRankedBarPattern & other ) const;
 
-	virtual void operator >>( std::ostream & out ) const;
+	/**
+	 * @copydoc alib::CommonBase<ObjectBase>::operator >> ( std::ostream & )
+	 */
+	virtual void operator >>( std::ostream & out ) const override;
 
-	virtual explicit operator std::string ( ) const;
+	/**
+	 * @copydoc alib::CommonBase<ObjectBase>::operator std::string ( )
+	 */
+	virtual explicit operator std::string ( ) const override;
 
+	/**
+	 * \brief The XML tag name of class.
+	 *
+	 * \details Intentionaly a static member function to be safe in the initialisation before the main function starts.
+	 *
+	 * \returns string representing the XML tag name of the class
+	 */
 	static const std::string & getXmlTagName() {
 		static std::string xmlTagName = "PrefixRankedBarPattern";
 
 		return xmlTagName;
 	}
 
+	/**
+	 * Parsing from a sequence of xml tokens helper.
+	 *
+	 * \params input the iterator to sequence of xml tokens to parse from
+	 *
+	 * \returns the new instance of the pattern
+	 */
 	static PrefixRankedBarPattern parse ( ext::deque < sax::Token >::iterator & input );
 
+	/**
+	 * Composing to a sequence of xml tokens helper.
+	 *
+	 * \param out the sink for new xml tokens representing the pattern
+	 * \param pattern the pattern to compose
+	 */
 	static void compose ( ext::deque < sax::Token > & out, const PrefixRankedBarPattern & pattern );
 
-	virtual object::ObjectBase * inc ( ) &&;
+	/**
+	 * @copydoc alib::ObjectBase::inc()
+	 */
+	virtual object::ObjectBase * inc ( ) && override;
 
+	/**
+	 * Type of normalized pattern.
+	 */
 	typedef PrefixRankedBarPattern < > normalized_type;
 };
 
@@ -301,66 +487,171 @@ object::ObjectBase* PrefixRankedBarPattern < SymbolType, RankType >::inc() && {
 
 namespace core {
 
+/**
+ * Helper class specifying constraints for the pattern's internal alphabet component.
+ *
+ * \tparam SymbolType used for the symbol part of the ranked symbols of the alphabet of the pattern.
+ * \tparam RankType used for the rank part of the ranked symbols of the alphabet of the pattern.
+ */
 template < class SymbolType, class RankType >
 class SetConstraint< ::tree::PrefixRankedBarPattern < SymbolType, RankType >, common::ranked_symbol < SymbolType, RankType >, ::tree::GeneralAlphabet > {
 public:
+	/**
+	 * Returns true if the symbol is still used in the pattern.
+	 *
+	 * \param pattern the tested pattern
+	 * \param symbol the tested symbol
+	 *
+	 * \returns true if the symbol is used, false othervise
+	 */
 	static bool used ( const ::tree::PrefixRankedBarPattern < SymbolType, RankType > & pattern, const common::ranked_symbol < SymbolType, RankType > & symbol ) {
 		const ext::vector < common::ranked_symbol < SymbolType, RankType > > & content = pattern.getContent ( );
 
 		return std::find ( content.begin ( ), content.end ( ), symbol ) != content.end ( ) || pattern.template accessComponent < ::tree::VariablesBarSymbol > ( ).get ( ) == symbol || pattern.template accessComponent < ::tree::BarSymbols > ( ).get ( ).count ( symbol ) || pattern.template accessComponent < ::tree::SubtreeWildcard > ( ).get ( ) == symbol;
 	}
 
+	/**
+	 * Returns true as all symbols are possibly available to be in an alphabet.
+	 *
+	 * \param pattern the tested pattern
+	 * \param symbol the tested symbol
+	 *
+	 * \returns true
+	 */
 	static bool available ( const ::tree::PrefixRankedBarPattern < SymbolType, RankType > &, const common::ranked_symbol < SymbolType, RankType > & ) {
 		return true;
 	}
 
+	/**
+	 * All symbols are valid as symbols of an alphabet.
+	 *
+	 * \param pattern the tested pattern
+	 * \param symbol the tested symbol
+	 */
 	static void valid ( const ::tree::PrefixRankedBarPattern < SymbolType, RankType > &, const common::ranked_symbol < SymbolType, RankType > & ) {
 	}
 };
 
+/**
+ * Helper class specifying constraints for the pattern's internal bar set component.
+ *
+ * \tparam SymbolType used for the symbol part of the ranked symbols of the alphabet of the pattern.
+ * \tparam RankType used for the rank part of the ranked symbols of the alphabet of the pattern.
+ */
 template < class SymbolType, class RankType >
 class SetConstraint< ::tree::PrefixRankedBarPattern < SymbolType, RankType >, common::ranked_symbol < SymbolType, RankType >, ::tree::BarSymbols > {
 public:
+	/**
+	 * Returns true if the symbol is still used in the pattern.
+	 *
+	 * \param pattern the tested pattern
+	 * \param symbol the tested symbol
+	 *
+	 * \returns true if the symbol is used, false othervise
+	 */
 	static bool used ( const ::tree::PrefixRankedBarPattern < SymbolType, RankType > & pattern, const common::ranked_symbol < SymbolType, RankType > & symbol ) {
 		const ext::vector < common::ranked_symbol < SymbolType, RankType > > & content = pattern.getContent ( );
 
 		return std::find ( content.begin ( ), content.end ( ), symbol ) != content.end ( ) || pattern.template accessComponent < ::tree::VariablesBarSymbol > ( ).get ( ) == symbol;
 	}
 
+	/**
+	 * Determines whether the symbol is available in the pattern's alphabet.
+	 *
+	 * \param pattern the tested pattern
+	 * \param symbol the tested symbol
+	 *
+	 * \returns true if the symbol is already in the alphabet of the pattern
+	 */
 	static bool available ( const ::tree::PrefixRankedBarPattern < SymbolType, RankType > & pattern, const common::ranked_symbol < SymbolType, RankType > & symbol ) {
 		return pattern.template accessComponent < ::tree::GeneralAlphabet > ( ).get ( ).count ( symbol );
 	}
 
+	/**
+	 * All symbols are valid as a bar symbol of the pattern.
+	 *
+	 * \param pattern the tested pattern
+	 * \param symbol the tested symbol
+	 */
 	static void valid ( const ::tree::PrefixRankedBarPattern < SymbolType, RankType > &, const common::ranked_symbol < SymbolType, RankType > & ) {
 	}
 };
 
+/**
+ * Helper class specifying constraints for the pattern's internal subtree wildcard element.
+ *
+ * \tparam SymbolType used for the symbol part of the ranked symbols of the alphabet of the pattern.
+ * \tparam RankType used for the rank part of the ranked symbols of the alphabet of the pattern.
+ */
 template < class SymbolType, class RankType >
 class ElementConstraint< ::tree::PrefixRankedBarPattern < SymbolType, RankType >, common::ranked_symbol < SymbolType, RankType >, ::tree::SubtreeWildcard > {
 public:
+	/**
+	 * Determines whether the symbol is available in the pattern's alphabet.
+	 *
+	 * \param pattern the tested pattern
+	 * \param symbol the tested symbol
+	 *
+	 * \returns true if the symbol is already in the alphabet of the pattern
+	 */
 	static bool available ( const ::tree::PrefixRankedBarPattern < SymbolType, RankType > & pattern, const common::ranked_symbol < SymbolType, RankType > & symbol ) {
 		return pattern.template accessComponent < ::tree::GeneralAlphabet > ( ).get ( ).count ( symbol );
 }
 
+	/**
+	 * Subtree wildcard needs to have zero arity.
+	 *
+	 * \param pattern the tested pattern
+	 * \param symbol the tested symbol
+	 *
+	 * \throws TreeException if the symbol does not have zero arity
+	 */
 	static void valid ( const ::tree::PrefixRankedBarPattern < SymbolType, RankType > &, const common::ranked_symbol < SymbolType, RankType > & symbol) {
 		if( ( unsigned ) symbol.getRank() != 0 )
 			throw ::tree::TreeException ( "SubtreeWildcard symbol has nonzero arity" );
 	}
 };
 
+/**
+ * Helper class specifying constraints for the pattern's internal variables bar element.
+ *
+ * \tparam SymbolType used for the symbol part of the ranked symbols of the alphabet of the pattern.
+ * \tparam RankType used for the rank part of the ranked symbols of the alphabet of the pattern.
+ */
 template < class SymbolType, class RankType >
 class ElementConstraint< ::tree::PrefixRankedBarPattern < SymbolType, RankType >, common::ranked_symbol < SymbolType, RankType >, ::tree::VariablesBarSymbol > {
 public:
+	/**
+	 * Determines whether the symbol is available in the pattern's alphabet.
+	 *
+	 * \param pattern the tested pattern
+	 * \param symbol the tested symbol
+	 *
+	 * \returns true if the symbol is already in the alphabet of the pattern
+	 */
 	static bool available ( const ::tree::PrefixRankedBarPattern < SymbolType, RankType > & pattern, const common::ranked_symbol < SymbolType, RankType > & symbol ) {
-		return pattern.template accessComponent < ::tree::BarSymbols > ( ).get ( ).count ( symbol );
+		return pattern.template accessComponent < tree::BarSymbols > ( ).get ( ).count ( symbol );
 	}
 
+	/**
+	 * Variables bar needs to have zero arity.
+	 *
+	 * \param pattern the tested pattern
+	 * \param symbol the tested symbol
+	 *
+	 * \throws TreeException if the symbol does not have zero arity
+	 */
 	static void valid ( const ::tree::PrefixRankedBarPattern < SymbolType, RankType > &, const common::ranked_symbol < SymbolType, RankType > & symbol) {
 		if( ( unsigned ) symbol.getRank() != 0 )
-			throw ::tree::TreeException ( "VariablesBarSymbol has nonzero arity" );
+			throw tree::TreeException ( "VariablesBarSymbol has nonzero arity" );
 	}
 };
 
+/**
+ * Helper for normalisation of types specified by templates used as internal datatypes of symbols.
+ *
+ * \returns new instance of the tree with default template parameters or unmodified instance if the template parameters were already default ones
+ */
 template < class SymbolType, class RankType >
 struct normalize < tree::PrefixRankedBarPattern < SymbolType, RankType >, typename std::enable_if < ! std::is_same < tree::PrefixRankedBarPattern < SymbolType, RankType >, tree::PrefixRankedBarPattern < > >::value >::type > {
 	static tree::PrefixRankedBarPattern < > eval ( tree::PrefixRankedBarPattern < SymbolType, RankType > && value ) {
diff --git a/alib2data/src/tree/ranked/PrefixRankedBarTree.h b/alib2data/src/tree/ranked/PrefixRankedBarTree.h
index 568a4f621d..ad0e7b61ee 100644
--- a/alib2data/src/tree/ranked/PrefixRankedBarTree.h
+++ b/alib2data/src/tree/ranked/PrefixRankedBarTree.h
@@ -1,6 +1,22 @@
 /*
  * PrefixRankedBarTree.h
  *
+ * This file is part of Algorithms library toolkit.
+ * Copyright (C) 2017 Jan Travnicek (jan.travnicek@fit.cvut.cz)
+
+ * Algorithms library toolkit is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+
+ * Algorithms library toolkit is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+
+ * You should have received a copy of the GNU General Public License
+ * along with Algorithms library toolkit.  If not, see <http://www.gnu.org/licenses/>.
+ *
  *  Created on: Nov 23, 2013
  *      Author: Jan Travnicek
  */
@@ -39,86 +55,225 @@ class GeneralAlphabet;
 class BarSymbols;
 
 /**
- * Represents regular expression parsed from the XML. Regular expression is stored
- * as a tree of LinearStringElement.
+ * \brief
+ * Tree structure represented as linear sequece as result of preorder traversal with additional bar symbols. The representation is so called ranked, therefore it consists of ranked symbols (bars are ranked as well). The rank of the ranked symbol need to compatible with unsigned integer.
+ *
+ * The bars represent end mark of all subtrees in the notation.
+ *
+ * \details
+ * T = (A, B \subset A, C),
+ * A (Alphabet) = finite set of ranked symbols,
+ * B (Bars) = finite set of ranked symbols representing bars,
+ * C (Content) = linear representation of the tree content
+ *
+ * \tparam SymbolType used for the symbol part of the ranked symbol
+ * \tparam RankType used for the rank part of the ranked symbol
  */
 template < class SymbolType, class RankType >
 class PrefixRankedBarTree final : public TreeBase, public core::Components < PrefixRankedBarTree < SymbolType, RankType >, ext::set < common::ranked_symbol < SymbolType, RankType > >, component::Set, std::tuple < GeneralAlphabet, BarSymbols > > {
+	/**
+	 * Linear representation of the tree content.
+	 */
 	ext::vector < common::ranked_symbol < SymbolType, RankType > > m_Data;
 
+	/**
+	 * Checker of validity of the representation of the tree
+	 *
+	 * \throws TreeException when new tree representation is not valid
+	 */
+	void arityChecksum ( const ext::vector < common::ranked_symbol < SymbolType, RankType > > & data );
+
 public:
+	/**
+	 * \brief Creates a new instance of the tree with concrete alphabet, bars, and content.
+	 *
+	 * \param bars the initial bar set
+	 * \param alphabet the initial alphabet of the tree
+	 * \param data the initial tree in linear representation
+	 */
 	explicit PrefixRankedBarTree ( ext::set < common::ranked_symbol < SymbolType, RankType > > bars, ext::set < common::ranked_symbol < SymbolType, RankType > > alphabet, ext::vector < common::ranked_symbol < SymbolType, RankType > > data );
+
+	/**
+	 * \brief Creates a new instance of the tree based on the content and bar set, the alphabet is implicitly created from the content.
+	 *
+	 * \param bars the initial bar set
+	 * \param data the initial tree in linear representation
+	 */
 	explicit PrefixRankedBarTree ( ext::set < common::ranked_symbol < SymbolType, RankType > > bars, ext::vector < common::ranked_symbol < SymbolType, RankType > > data );
+
+	/**
+	 * \brief Creates a new instance of the tree based on the RankedTree. The linear representation is constructed (including bars) by preorder traversal on the tree parameter. All bar symbols (ranked symbols) have the symbol part created from the barBase parameter. The rank part of each bar is computed according to the number of children of the respective node.
+	 *
+	 * \param barBase a symbol to be used as symbol part of a ranked symbol of each bar.
+	 * \param tree RankedTree representation of a tree.
+	 */
 	explicit PrefixRankedBarTree ( SymbolType barBase, const RankedTree < SymbolType, RankType > & tree );
+
+	/**
+	 * \brief Creates a new instance of the tree based on the RankedTree. The linear representation is constructed (including bars) by preorder traversal on the tree parameter. Bar symbols are created using some default value.
+	 *
+	 * \param tree RankedTree representation of a tree.
+	 */
 	explicit PrefixRankedBarTree ( const RankedTree < > & tree );
 
-	virtual TreeBase * clone ( ) const;
-	virtual TreeBase * plunder ( ) &&;
+	/**
+	 * @copydoc tree::TreeBase::clone()
+	 */
+	virtual TreeBase * clone ( ) const override;
 
+	/**
+	 * @copydoc tree::TreeBase::plunder()
+	 */
+	virtual TreeBase * plunder ( ) && override;
+
+	/**
+	 * Getter of the alphabet.
+	 *
+	 * \returns the alphabet of the tree
+	 */
 	const ext::set < common::ranked_symbol < SymbolType, RankType > > & getAlphabet ( ) const & {
 		return this->template accessComponent < GeneralAlphabet > ( ).get ( );
 	}
 
+	/**
+	 * Getter of the alphabet.
+	 *
+	 * \returns the alphabet of the tree
+	 */
 	ext::set < common::ranked_symbol < SymbolType, RankType > > && getAlphabet ( ) && {
 		return std::move ( this->template accessComponent < GeneralAlphabet > ( ).get ( ) );
 	}
 
+	/**
+	 * Adder of an alphabet symbols.
+	 *
+	 * \param symbols the new symbols to be added to the alphabet
+	 */
 	void extendAlphabet ( const ext::set < common::ranked_symbol < SymbolType, RankType > > & symbols ) {
 		this->template accessComponent < GeneralAlphabet > ( ).add ( symbols );
 	}
 
+	/**
+	 * Getter of the bar set.
+	 *
+	 * \returns the bar set of the tree
+	 */
 	const ext::set < common::ranked_symbol < SymbolType, RankType > > & getBars ( ) const & {
 		return this->template accessComponent < BarSymbols > ( ).get ( );
 	}
 
+	/**
+	 * Getter of the bar set.
+	 *
+	 * \returns the bar set of the tree
+	 */
 	ext::set < common::ranked_symbol < SymbolType, RankType > > && getBars ( ) && {
 		return std::move ( this->template accessComponent < BarSymbols > ( ).get ( ) );
 	}
 
+	/**
+	 * Adder of symbols to a bar set.
+	 *
+	 * \param symbols the new symbols to be added to the bar set
+	 */
 	void extendBars ( const ext::set < common::ranked_symbol < SymbolType, RankType > > & bars ) {
 		this->template accessComponent < BarSymbols > ( ).add ( bars );
 	}
 
 	/**
-	 * @return List of symbols forming tree (const version).
+	 * Getter of the tree representation.
+	 *
+	 * \return List of symbols forming the linear representation of the tree.
 	 */
 	const ext::vector < common::ranked_symbol < SymbolType, RankType > > & getContent ( ) const &;
 
+	/**
+	 * Getter of the tree representation.
+	 *
+	 * \return List of symbols forming the linear representation of the tree.
+	 */
 	ext::vector < common::ranked_symbol < SymbolType, RankType > > && getContent ( ) && ;
 
+	/**
+	 * Setter of the representation of the tree.
+	 *
+	 * \throws TreeException when new tree representation is not valid or when symbol of the representation are not present in the alphabet
+	 *
+	 * \param data new List of symbols forming the representation of the tree.
+	 */
 	void setContent ( ext::vector < common::ranked_symbol < SymbolType, RankType > > data );
 
-	void arityChecksum ( const ext::vector < common::ranked_symbol < SymbolType, RankType > > & data );
-
 	/**
-	 * @return true if tree is an empty word (vector length is 0)
+	 * @return true if tree is an empty word (vector length is 0). The method is present to allow compatibility with strings. Tree is never empty in this datatype.
 	 */
 	bool isEmpty ( ) const;
 
-	virtual int compare ( const ObjectBase & other ) const {
+	/**
+	 * @copydoc alib::CommonBase<ObjectBase>::compare ( const ObjectBase & )
+	 */
+	virtual int compare ( const ObjectBase & other ) const override {
 		if ( ext::type_index ( typeid ( * this ) ) == ext::type_index ( typeid ( other ) ) ) return this->compare ( ( decltype ( * this ) )other );
 
 		return ext::type_index ( typeid ( * this ) ) - ext::type_index ( typeid ( other ) );
 	}
 
-	virtual int compare ( const PrefixRankedBarTree & other ) const;
+	/**
+	 * The actual compare method
+	 *
+	 * \param other the other instance
+	 *
+	 * \returns the actual relation between two by type same tree instances
+	 */
+	int compare ( const PrefixRankedBarTree & other ) const;
 
-	virtual void operator >>( std::ostream & out ) const;
+	/**
+	 * @copydoc alib::CommonBase<ObjectBase>::operator >> ( std::ostream & )
+	 */
+	virtual void operator >>( std::ostream & out ) const override;
 
-	virtual explicit operator std::string ( ) const;
+	/**
+	 * @copydoc alib::CommonBase<ObjectBase>::operator std::string ( )
+	 */
+	virtual explicit operator std::string ( ) const override;
 
+	/**
+	 * \brief The XML tag name of class.
+	 *
+	 * \details Intentionaly a static member function to be safe in the initialisation before the main function starts.
+	 *
+	 * \returns string representing the XML tag name of the class
+	 */
 	static const std::string & getXmlTagName() {
 		static std::string xmlTagName = "PrefixRankedBarTree";
 
 		return xmlTagName;
 	}
 
+	/**
+	 * Parsing from a sequence of xml tokens helper.
+	 *
+	 * \params input the iterator to sequence of xml tokens to parse from
+	 *
+	 * \returns the new instance of the tree
+	 */
 	static PrefixRankedBarTree parse ( ext::deque < sax::Token >::iterator & input );
 
+	/**
+	 * Composing to a sequence of xml tokens helper.
+	 *
+	 * \param out the sink for new xml tokens representing the tree
+	 * \param tree the tree to compose
+	 */
 	static void compose ( ext::deque < sax::Token > & out, const PrefixRankedBarTree & tree );
 
-	virtual object::ObjectBase * inc ( ) &&;
+	/**
+	 * @copydoc alib::ObjectBase::inc()
+	 */
+	virtual object::ObjectBase * inc ( ) && override;
 
+	/**
+	 * Type of normalized tree.
+	 */
 	typedef PrefixRankedBarTree < > normalized_type;
 };
 
@@ -266,40 +421,101 @@ object::ObjectBase* PrefixRankedBarTree < SymbolType, RankType >::inc() && {
 
 namespace core {
 
+/**
+ * Helper class specifying constraints for the tree's internal alphabet component.
+ *
+ * \tparam SymbolType used for the symbol part of the ranked symbols of the alphabet of the pattern.
+ * \tparam RankType used for the rank part of the ranked symbols of the alphabet of the pattern.
+ */
 template < class SymbolType, class RankType >
 class SetConstraint< ::tree::PrefixRankedBarTree < SymbolType, RankType >, common::ranked_symbol < SymbolType, RankType >, ::tree::GeneralAlphabet > {
 public:
+	/**
+	 * Returns true if the symbol is still used in the tree.
+	 *
+	 * \param tree the tested tree
+	 * \param symbol the tested symbol
+	 *
+	 * \returns true if the symbol is used, false othervise
+	 */
 	static bool used ( const ::tree::PrefixRankedBarTree < SymbolType, RankType > & tree, const common::ranked_symbol < SymbolType, RankType > & symbol ) {
 		const ext::vector < common::ranked_symbol < SymbolType, RankType > > & content = tree.getContent ( );
 
 		return std::find ( content.begin ( ), content.end ( ), symbol ) != content.end ( );
 	}
 
+	/**
+	 * Returns true as all symbols are possibly available to be in an alphabet.
+	 *
+	 * \param tree the tested tree
+	 * \param symbol the tested symbol
+	 *
+	 * \returns true
+	 */
 	static bool available ( const ::tree::PrefixRankedBarTree < SymbolType, RankType > &, const common::ranked_symbol < SymbolType, RankType > & ) {
 		return true;
 	}
 
+	/**
+	 * All symbols are valid as symbols of an alphabet.
+	 *
+	 * \param tree the tested tree
+	 * \param symbol the tested symbol
+	 */
 	static void valid ( const ::tree::PrefixRankedBarTree < SymbolType, RankType > &, const common::ranked_symbol < SymbolType, RankType > & ) {
 	}
 };
 
+/**
+ * Helper class specifying constraints for the tree's internal bar set component.
+ *
+ * \tparam SymbolType used for the symbol part of the ranked symbols of the alphabet of the pattern.
+ * \tparam RankType used for the rank part of the ranked symbols of the alphabet of the pattern.
+ */
 template < class SymbolType, class RankType >
 class SetConstraint< ::tree::PrefixRankedBarTree < SymbolType, RankType >, common::ranked_symbol < SymbolType, RankType >, ::tree::BarSymbols > {
 public:
+	/**
+	 * Returns true if the symbol is still used in the tree.
+	 *
+	 * \param tree the tested tree
+	 * \param symbol the tested symbol
+	 *
+	 * \returns true if the symbol is used, false othervise
+	 */
 	static bool used ( const ::tree::PrefixRankedBarTree < SymbolType, RankType > & tree, const common::ranked_symbol < SymbolType, RankType > & symbol ) {
 		const ext::vector < common::ranked_symbol < SymbolType, RankType > > & content = tree.getContent ( );
 
 		return std::find ( content.begin ( ), content.end ( ), symbol ) != content.end ( );
 	}
 
+	/**
+	 * Determines whether the symbol is available in the tree's alphabet.
+	 *
+	 * \param tree the tested tree
+	 * \param symbol the tested symbol
+	 *
+	 * \returns true if the symbol is already in the bar set of the tree
+	 */
 	static bool available ( const ::tree::PrefixRankedBarTree < SymbolType, RankType > & tree, const common::ranked_symbol < SymbolType, RankType > & symbol ) {
 		return tree.template accessComponent < ::tree::GeneralAlphabet > ( ).get ( ).count ( symbol );
 	}
 
+	/**
+	 * All symbols are valid as a bar symbol of the tree.
+	 *
+	 * \param tree the tested tree
+	 * \param symbol the tested symbol
+	 */
 	static void valid ( const ::tree::PrefixRankedBarTree < SymbolType, RankType > &, const common::ranked_symbol < SymbolType, RankType > & ) {
 	}
 };
 
+/**
+ * Helper for normalisation of types specified by templates used as internal datatypes of symbols.
+ *
+ * \returns new instance of the tree with default template parameters or unmodified instance if the template parameters were already default ones
+ */
 template < class SymbolType, class RankType >
 struct normalize < tree::PrefixRankedBarTree < SymbolType, RankType >, typename std::enable_if < ! std::is_same < tree::PrefixRankedBarTree < SymbolType, RankType >, tree::PrefixRankedBarTree < > >::value >::type > {
 	static tree::PrefixRankedBarTree < > eval ( tree::PrefixRankedBarTree < SymbolType, RankType > && value ) {
diff --git a/alib2data/src/tree/ranked/PrefixRankedTree.h b/alib2data/src/tree/ranked/PrefixRankedTree.h
index 9b012564fb..d25f3b29f3 100644
--- a/alib2data/src/tree/ranked/PrefixRankedTree.h
+++ b/alib2data/src/tree/ranked/PrefixRankedTree.h
@@ -376,7 +376,8 @@ namespace core {
 /**
  * Helper class specifying constraints for the tree's internal alphabet component.
  *
- * \tparam SymbolType used for the alphabet of the tree.
+ * \tparam SymbolType used for the symbol part of the ranked symbols of the alphabet of the pattern.
+ * \tparam RankType used for the rank part of the ranked symbols of the alphabet of the pattern.
  */
 template < class SymbolType, class RankType >
 class SetConstraint< ::tree::PrefixRankedTree < SymbolType, RankType >, common::ranked_symbol < SymbolType, RankType >, ::tree::GeneralAlphabet > {
diff --git a/alib2data/src/tree/ranked/RankedTree.h b/alib2data/src/tree/ranked/RankedTree.h
index e63a6100b6..7a7babb8af 100644
--- a/alib2data/src/tree/ranked/RankedTree.h
+++ b/alib2data/src/tree/ranked/RankedTree.h
@@ -385,7 +385,8 @@ namespace core {
 /**
  * Helper class specifying constraints for the tree's internal alphabet component.
  *
- * \tparam SymbolType used for the alphabet of the tree.
+ * \tparam SymbolType used for the symbol part of the ranked symbols of the alphabet of the pattern.
+ * \tparam RankType used for the rank part of the ranked symbols of the alphabet of the pattern.
  */
 template < class SymbolType, class RankType >
 class SetConstraint< ::tree::RankedTree < SymbolType, RankType >, common::ranked_symbol < SymbolType, RankType >, ::tree::GeneralAlphabet > {
-- 
GitLab