Add some comments

include/core/utils/converter.h

@@ -20,9 +20,35 @@
 
 /**
    @file
+   converter.h
+   @brief This file implements a set of simple functions that deal with the correspondence between
+   classes and their string representation. The YAML autosetup framework makes heavy use of this file.
+ */
+
+//Note: In order to deal with string representations we make heavy use of regexps.
+//      We use the standard C++11 regular expressions capabilities.
+
+/*
+** This file is structured essentially in two parts:
+** in the first part (which starts after the CONVERTERS ~~~~ STRING ----> TYPE line)
+** we have functions to convert from string to C++ class. For example:
+     string v1 = "[3,4,5,6,7,8,9,10,11]";
+     vector<int> v = converter<vector<int>>::convert(v1);
+   This code snippet transforms the string v1 which represents an std::vector into an actual std::vector value.
+   The second part (which starts after the TYPES ----> ToSTRING line) has the functions to
+   transform from C++ classes to strings. For instance, if we wanted to convert from a C++ class
+   to a string we would do something like this:
+     vector<int> vect{ 10, 20, 30 };
+     string str = converter<std::string>::convert(vect);
+     //str == "[10,20,30]"
  */
 namespace wolf{
 
+    //This definition is a bit of a "hack". The reason of redefining the pair class is to be able
+    //to have two string representations of a pair, namely
+    //"(·,·)" -> typical pair/tuple representation
+    //"{·,·}" -> key-value pair representation used to represent maps.
+    //This is purely an aesthetic reason and could be removed without problems.
 template<class A, class B>
 struct Wpair : std::pair<A,B>
 {

src/yaml/parser_yaml.cpp

@@ -345,6 +345,12 @@ void ParserYaml::updateActiveName(std::string _tag)
 {
     active_name_ = _tag;
 }
+/*
+** @brief This function is responsible for parsing the first level of the YAML file.
+** The first level here can be thought as the entry point of the YAML file. Since we impose a certain structure
+** this function is responsible for enforcing said structure.
+**
+ */
 void ParserYaml::parseFirstLevel(YAML::Node _n, std::string _file)
 {
 
@@ -550,6 +556,9 @@ void ParserYaml::parse()
     }
     parsing_file_.pop();
 }
+/*
+** @brief This function gives the ability to run the parser without enforcing the wolf YAML structure.
+ */
 void ParserYaml::parse_freely()
 {
     parsing_file_.push(generatePath(file_));