add function parameters description

Signed-off-by: SofiaFaraci <[email protected]>

code/include/ExtractFromElement.h

@@ -15,30 +15,30 @@
 /**
  * @brief Gets the value of a specific attribute of a given XML element
  * 
- * @param element 
- * @param attribute 
- * @param attributeValue 
+ * @param element element from which to get the attribute value
+ * @param attribute attribute name 
+ * @param attributeValue attribute value passed by reference
  * @return bool
  */
 bool getElementAttValue(tinyxml2::XMLElement* element, const std::string attribute, std::string& attributeValue);
 
 /**
  * @brief Gets the text of a given XML element
  * 
- * @param element 
- * @param textValue 
+ * @param element element from which to get the text
+ * @param textValue text value passed by reference
  * @return bool 
  */
 bool getElementText(tinyxml2::XMLElement* element, std::string& textValue);
 
 /**
  * @brief Find a XML element by tag and attribute name and value
  * 
- * @param root 
- * @param tag 
- * @param attributeName 
- * @param attributeValue 
- * @param element 
+ * @param root root element from which to start the search
+ * @param tag tag name to look for
+ * @param attributeName attribute name to look for inside the tag
+ * @param attributeValue attribute value associated with the attribute name
+ * @param element element found returned by reference
  * @return true 
  * @return false 
  */
@@ -47,9 +47,9 @@ bool findElementByTagAndAttValue(tinyxml2::XMLElement* root, const std::string t
 /**
  * @brief Find a XML element by tag
  * 
- * @param root 
- * @param tag 
- * @param element 
+ * @param root root element from which to start the search
+ * @param tag tag name to look for
+ * @param element element found returned by reference
  * @return true 
  * @return false 
  */
@@ -58,19 +58,19 @@ bool findElementByTag(tinyxml2::XMLElement* root, const std::string tag, tinyxml
 /**
  * @brief Find a vector of XML elements by tag and attribute name
  * 
- * @param root 
- * @param tag 
- * @param attribute 
- * @param elementVector 
+ * @param root root element from which to start the search
+ * @param tag tag name to look for
+ * @param attribute attribute name to look for inside the tag
+ * @param elementVector vector of elements found returned by reference
  */
 void findElementVectorByTagAndAttribute(tinyxml2::XMLElement* root, const std::string tag, const std::string attribute, std::vector<tinyxml2::XMLElement*>& elementVector);
 
 /**
  * @brief Find a vector of XML elements by tag
  * 
- * @param root 
- * @param tag 
- * @param elementVector 
+ * @param root root element from which to start the search
+ * @param tag tag name to look for
+ * @param elementVector vector of elements found returned by reference
  */
 void findElementVectorByTag(tinyxml2::XMLElement* root, const std::string tag, std::vector<tinyxml2::XMLElement*>& elementVector);
 

code/include/ExtractFromXML.h

@@ -11,17 +11,17 @@
 /**
  * @brief Extract the interface name from the model file
  * 
- * @param fileName 
- * @param eventData 
+ * @param fileName model file name
+ * @param eventData event data structure, where the interface name will be stored, returned by reference 
  * @return bool
  */
 bool extractInterfaceName(const std::string fileName, eventDataStr& eventData);
 
 /**
  * @brief Extract the interface data from the interface file
  * 
- * @param fileName 
- * @param eventData 
+ * @param fileName interface file name
+ * @param eventData event data structure, where the interface data will be stored, returned by reference
  * @return true 
  * @return false 
  */
@@ -30,11 +30,11 @@ bool extractInterfaceType(const std::string fileName, eventDataStr& eventData);
 /**
  * @brief Extract data from SCXML file
  * 
- * @param doc 
- * @param fileName 
- * @param rootName 
- * @param elementsTransition 
- * @param elementsSend 
+ * @param doc document object
+ * @param fileName scxml file name
+ * @param rootName root name
+ * @param elementsTransition vector of transition event elements 
+ * @param elementsSend vector of send event elements
  * @return true 
  * @return false 
  */

code/include/Generator.h

@@ -70,126 +70,128 @@ struct topicCodeStr
 /**
  * @brief Get component and function data from event name
  * 
- * @param eventData 
+ * @param eventData event data structure passed by reference from which the event string is extracted and the component and function data are stored
  */
 void getDataFromEvent(eventDataStr& eventData);
 
 /**
  * @brief Get the skill Data From SCXML Root Name object
  * 
- * @param attributeName 
- * @param skillData 
+ * @param attributeName root attribute name from which the skill data is extracted
+ * @param skillData skill data structure passed by reference where the skill data is stored
  * @return bool 
  */
 bool getDataFromRootName(const std::string attributeName, skillDataStr& skillData);
 
 /**
  * @brief Prints the event data
  * 
- * @param eventData 
+ * @param eventData event data structure to be printed
  */
 void printEventData(eventDataStr eventData);
 
 /**
  * @brief Prints the skill data
  * 
- * @param skillData 
+ * @param skillData skill data structure to be printed
  */
 void printSkillData(skillDataStr skillData);
 
 /**
  * @brief Process the event data
  * 
- * @param eventData 
- * @param skillData 
- * @param target 
- * @param hCode 
- * @param cppCode 
- * @param topicCode 
+ * @param fileData the file data structure contianing the model and the interface file paths
+ * @param eventData event data structure 
+ * @param skillData skill data structure
+ * @param target event target state
+ * @param hCode structure where the header code is stored
+ * @param cppCode structure where the cpp code is stored
+ * @param topicCode structure where the topic code is stored
  */
 void processEvent(fileDataStr fileData, eventDataStr eventData, const skillDataStr skillData, std::string target, hCodeStr& hCode, cppCodeStr& cppCode, topicCodeStr& topicCode);
 
 /**
  * @brief Generate the code for the events
  * 
- * @param elementsTransition 
- * @param elementsSend 
- * @param skillData 
- * @param hCode 
- * @param cppCode 
- * @param topicCode 
+ * @param fileData the file data structure contianing the model and the interface file paths
+ * @param elementsTransition vector of transition elements
+ * @param elementsSend vector of send elements
+ * @param skillData skill data structure
+ * @param hCode structure where the header code is stored
+ * @param cppCode structure where the cpp code is stored
+ * @param topicCode structure where the topic code is stored
  */
 void getEventsCode(fileDataStr fileData, const std::vector<tinyxml2::XMLElement*> elementsTransition, const std::vector<tinyxml2::XMLElement*> elementsSend, skillDataStr skillData, hCodeStr& hCode, cppCodeStr& cppCode, topicCodeStr& topicCode);
 
 /**
  * @brief Write the header code
  * 
- * @param skillData 
- * @param code 
- * @param datamodel_mode 
+ * @param skillData skill data structure 
+ * @param code code structure where the header code is stored
+ * @param datamodel_mode data model mode flag
  */
 void writeHCode(const skillDataStr skillData, hCodeStr& code, bool datamodel_mode);
 
 /**
  * @brief Write the cpp code
  * 
- * @param skillData 
- * @param code 
- * @param datamodel_mode 
+ * @param skillData skill data structure
+ * @param code code structure where the cpp code is stored
+ * @param datamodel_mode data model mode flag
  */
 void writeCppCode(const skillDataStr skillData, cppCodeStr& code, bool datamodel_mode);
 
 /**
  * @brief Write the header code for the data model
  * 
- * @param skillData 
- * @param code 
+ * @param skillData skill data structure
+ * @param code code structure where the data model header code is stored
  */
 void writeDataModelHCode(const skillDataStr skillData, hCodeStr& code);
 
 /**
  * @brief Write the cpp code for the data model
  * 
- * @param skillData 
- * @param code 
+ * @param skillData skill data structure
+ * @param code code structure where the data model cpp code is stored
  */
 void writeDataModelCppCode(const skillDataStr skillData, cppDataModelCodeStr& code);
 
 /**
  * @brief Generate the data model header file
  * 
- * @param outputPath 
- * @param outputFileName 
- * @param code 
+ * @param outputPath path where to save the output file
+ * @param outputFileName filename of the output file
+ * @param code code structure where the data model header code is stored
  */
 void generateDataModelHFile(const std::string outputPath, const std::string outputFileName, hCodeStr code);
 
 /**
  * @brief Generate the data model cpp file
  * 
- * @param outputPath 
- * @param outputFileName 
- * @param code 
+ * @param outputPath path where to save the output file
+ * @param outputFileName filename of the output file
+ * @param code code structure where the data model cpp code is stored
  */
 void generateDataModelCppFile(const std::string outputPath, const std::string outputFileName, cppDataModelCodeStr code);
 
 /**
  * @brief Generate the header file
  * 
- * @param outputPath 
- * @param outputFileName 
- * @param skillData 
- * @param code 
+ * @param outputPath path where to save the output file
+ * @param outputFileName filename of the output file
+ * @param skillData skill data structure
+ * @param code code structure where the header code is stored
  */
 void generateHFile(const std::string outputPath, const std::string outputFileName, const skillDataStr skillData, hCodeStr code);
 
 /**
  * @brief Generate the cpp file
  * 
- * @param outputPath 
- * @param outputFileName 
- * @param skillData 
- * @param code 
+ * @param outputPath path where to save the output file
+ * @param outputFileName filename of the output file
+ * @param skillData skill data structure
+ * @param code code structure where the cpp code is stored
  */
 void generateCppFile(const std::string outputPath, const std::string outputFileName, const skillDataStr skillData, cppCodeStr code);
 

code/include/utils.h

@@ -12,23 +12,23 @@
 /**
  * @brief Convert string to snake case
  * 
- * @param input 
- * @param output 
+ * @param input input string to be converted (e.g. "BatteryState")
+ * @param output output string converted to snake case (e.g. "battery_state")
  */
 void turnToSnakeCase(const std::string input, std::string& output);
 
 /**
- * @brief Get data type path from data type name (e.g. from "sensor_msgs::msg::BatteryState" to "sensor_msgs/msg/battery_state")
+ * @brief Get data type path from data type name
  * 
- * @param input 
- * @param output 
+ * @param input input data type name (e.g. from "sensor_msgs::msg::BatteryState")
+ * @param output output data type path (e.g. "sensor_msgs/msg/battery_state")
  */
 void getDataTypePath(const std::string input, std::string& output);
 
 /**
- * @brief Get the path 
+ * @brief Get the output path from the input file path
  * 
- * @param filePath 
- * @param output 
+ * @param filePath input file path (e.g. "templates/skills/first_template_skill/src/FirstTemplateSkillSM.scxml")
+ * @param output output path (e.g. "templates/skills/first_template_skill/")
  */
 void getPath(const std::string filePath, std::string& output);