From 6022b39d4f833508dc1f5f0e13902327ca6e06fd Mon Sep 17 00:00:00 2001 From: SofiaFaraci Date: Wed, 22 May 2024 10:14:05 +0200 Subject: [PATCH] add function parameters description Signed-off-by: SofiaFaraci --- code/include/ExtractFromElement.h | 40 +++++++-------- code/include/ExtractFromXML.h | 18 +++---- code/include/Generator.h | 84 ++++++++++++++++--------------- code/include/utils.h | 16 +++--- 4 files changed, 80 insertions(+), 78 deletions(-) diff --git a/code/include/ExtractFromElement.h b/code/include/ExtractFromElement.h index bf217c2..e2062c4 100644 --- a/code/include/ExtractFromElement.h +++ b/code/include/ExtractFromElement.h @@ -15,9 +15,9 @@ /** * @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); @@ -25,8 +25,8 @@ bool getElementAttValue(tinyxml2::XMLElement* element, const std::string attribu /** * @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); @@ -34,11 +34,11 @@ 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& 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& elementVector); diff --git a/code/include/ExtractFromXML.h b/code/include/ExtractFromXML.h index 4412364..5a0f2eb 100644 --- a/code/include/ExtractFromXML.h +++ b/code/include/ExtractFromXML.h @@ -11,8 +11,8 @@ /** * @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); @@ -20,8 +20,8 @@ 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 */ diff --git a/code/include/Generator.h b/code/include/Generator.h index eecb080..8d4e3f2 100644 --- a/code/include/Generator.h +++ b/code/include/Generator.h @@ -70,15 +70,15 @@ 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); @@ -86,110 +86,112 @@ bool getDataFromRootName(const std::string attributeName, skillDataStr& skillDat /** * @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 elementsTransition, const std::vector 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); diff --git a/code/include/utils.h b/code/include/utils.h index 83b56c7..898602a 100644 --- a/code/include/utils.h +++ b/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);