From e573154f7bc3c63c4530544b9e8c63ca4cb978a8 Mon Sep 17 00:00:00 2001 From: SofiaFaraci Date: Tue, 21 May 2024 17:22:52 +0200 Subject: [PATCH] add doxygen dependency and documentation to h files Signed-off-by: SofiaFaraci --- .github/workflows/deploy.yml | 3 + code/include/ExtractFromElement.h | 62 ++++++++++++-- code/include/ExtractFromXML.h | 32 ++++++- code/include/Generator.h | 138 ++++++++++++++++++++++++++---- code/include/utils.h | 24 +++++- code/src/utils.cpp | 6 ++ 6 files changed, 238 insertions(+), 27 deletions(-) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 7a4d616..effd3aa 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -16,6 +16,9 @@ jobs: # install the dependencies - name: Install dependencies run: pip install -r docs/requirements.txt + # install doxygen + - name: Install doxygen + run: sudo apt install doxygen # build the documentation - name: Build documentation run: | diff --git a/code/include/ExtractFromElement.h b/code/include/ExtractFromElement.h index 0657864..bf217c2 100644 --- a/code/include/ExtractFromElement.h +++ b/code/include/ExtractFromElement.h @@ -12,15 +12,65 @@ #include #include -bool getElementAttValue(tinyxml2::XMLElement*, const std::string, std::string& ); +/** + * @brief Gets the value of a specific attribute of a given XML element + * + * @param element + * @param attribute + * @param attributeValue + * @return bool + */ +bool getElementAttValue(tinyxml2::XMLElement* element, const std::string attribute, std::string& attributeValue); -bool getElementText(tinyxml2::XMLElement*, std::string& ); +/** + * @brief Gets the text of a given XML element + * + * @param element + * @param textValue + * @return bool + */ +bool getElementText(tinyxml2::XMLElement* element, std::string& textValue); -bool findElementByTagAndAttValue(tinyxml2::XMLElement* root, const std::string tag, const std::string, const std::string, tinyxml2::XMLElement*& ); +/** + * @brief Find a XML element by tag and attribute name and value + * + * @param root + * @param tag + * @param attributeName + * @param attributeValue + * @param element + * @return true + * @return false + */ +bool findElementByTagAndAttValue(tinyxml2::XMLElement* root, const std::string tag, const std::string attributeName, const std::string attributeValue, tinyxml2::XMLElement*& element); -bool findElementByTag(tinyxml2::XMLElement*, const std::string, tinyxml2::XMLElement*& ); +/** + * @brief Find a XML element by tag + * + * @param root + * @param tag + * @param element + * @return true + * @return false + */ +bool findElementByTag(tinyxml2::XMLElement* root, const std::string tag, tinyxml2::XMLElement*& element); -void findElementVectorByTagAndAttribute(tinyxml2::XMLElement*, const std::string, const std::string, std::vector&); +/** + * @brief Find a vector of XML elements by tag and attribute name + * + * @param root + * @param tag + * @param attribute + * @param elementVector + */ +void findElementVectorByTagAndAttribute(tinyxml2::XMLElement* root, const std::string tag, const std::string attribute, std::vector& elementVector); -void findElementVectorByTag(tinyxml2::XMLElement*, const std::string, std::vector&); +/** + * @brief Find a vector of XML elements by tag + * + * @param root + * @param tag + * @param elementVector + */ +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 f6111d0..4412364 100644 --- a/code/include/ExtractFromXML.h +++ b/code/include/ExtractFromXML.h @@ -8,8 +8,34 @@ #include "Data.h" #include "ExtractFromElement.h" -bool extractInterfaceName(const std::string, eventDataStr&); +/** + * @brief Extract the interface name from the model file + * + * @param fileName + * @param eventData + * @return bool + */ +bool extractInterfaceName(const std::string fileName, eventDataStr& eventData); -bool extractInterfaceType(const std::string, eventDataStr&); +/** + * @brief Extract the interface data from the interface file + * + * @param fileName + * @param eventData + * @return true + * @return false + */ +bool extractInterfaceType(const std::string fileName, eventDataStr& eventData); -bool extractFromSCXML(tinyxml2::XMLDocument&, const std::string, std::string&, std::vector&, std::vector&); +/** + * @brief Extract data from SCXML file + * + * @param doc + * @param fileName + * @param rootName + * @param elementsTransition + * @param elementsSend + * @return true + * @return false + */ +bool extractFromSCXML(tinyxml2::XMLDocument& doc, const std::string fileName, std::string& rootName, std::vector& elementsTransition, std::vector& elementsSend); diff --git a/code/include/Generator.h b/code/include/Generator.h index d09f0fc..eecb080 100644 --- a/code/include/Generator.h +++ b/code/include/Generator.h @@ -67,37 +67,145 @@ struct topicCodeStr std::string callbacksCode; }; +/** + * @brief Get component and function data from event name + * + * @param eventData + */ +void getDataFromEvent(eventDataStr& eventData); -void getDataFromEvent(eventDataStr&); - -bool getDataFromRootName(const std::string, skillDataStr&); +/** + * @brief Get the skill Data From SCXML Root Name object + * + * @param attributeName + * @param skillData + * @return bool + */ +bool getDataFromRootName(const std::string attributeName, skillDataStr& skillData); -void printEventData(eventDataStr); +/** + * @brief Prints the event data + * + * @param eventData + */ +void printEventData(eventDataStr eventData); -void printSkillData(skillDataStr); +/** + * @brief Prints the skill data + * + * @param skillData + */ +void printSkillData(skillDataStr skillData); -void processEvent(fileDataStr fileData, eventDataStr, const skillDataStr, std::string, hCodeStr&, cppCodeStr&, topicCodeStr&); +/** + * @brief Process the event data + * + * @param eventData + * @param skillData + * @param target + * @param hCode + * @param cppCode + * @param topicCode + */ +void processEvent(fileDataStr fileData, eventDataStr eventData, const skillDataStr skillData, std::string target, hCodeStr& hCode, cppCodeStr& cppCode, topicCodeStr& topicCode); -void getEventsCode(fileDataStr fileData, const std::vector, const std::vector, skillDataStr, hCodeStr&, cppCodeStr&, topicCodeStr&); +/** + * @brief Generate the code for the events + * + * @param elementsTransition + * @param elementsSend + * @param skillData + * @param hCode + * @param cppCode + * @param topicCode + */ +void getEventsCode(fileDataStr fileData, const std::vector elementsTransition, const std::vector elementsSend, skillDataStr skillData, hCodeStr& hCode, cppCodeStr& cppCode, topicCodeStr& topicCode); -void writeHCode(const skillDataStr, hCodeStr&, bool); +/** + * @brief Write the header code + * + * @param skillData + * @param code + * @param datamodel_mode + */ +void writeHCode(const skillDataStr skillData, hCodeStr& code, bool datamodel_mode); -void writeCppCode(const skillDataStr, cppCodeStr&, bool); +/** + * @brief Write the cpp code + * + * @param skillData + * @param code + * @param datamodel_mode + */ +void writeCppCode(const skillDataStr skillData, cppCodeStr& code, bool datamodel_mode); -void writeDataModelHCode(const skillDataStr, hCodeStr&); +/** + * @brief Write the header code for the data model + * + * @param skillData + * @param code + */ +void writeDataModelHCode(const skillDataStr skillData, hCodeStr& code); -void writeDataModelCppCode(const skillDataStr, cppDataModelCodeStr&); +/** + * @brief Write the cpp code for the data model + * + * @param skillData + * @param code + */ +void writeDataModelCppCode(const skillDataStr skillData, cppDataModelCodeStr& code); -void generateDataModelHFile(const std::string, const std::string, hCodeStr); +/** + * @brief Generate the data model header file + * + * @param outputPath + * @param outputFileName + * @param code + */ +void generateDataModelHFile(const std::string outputPath, const std::string outputFileName, hCodeStr code); -void generateDataModelCppFile(const std::string, const std::string, cppDataModelCodeStr); +/** + * @brief Generate the data model cpp file + * + * @param outputPath + * @param outputFileName + * @param code + */ +void generateDataModelCppFile(const std::string outputPath, const std::string outputFileName, cppDataModelCodeStr code); -void generateHFile(const std::string, const std::string, const skillDataStr, hCodeStr); +/** + * @brief Generate the header file + * + * @param outputPath + * @param outputFileName + * @param skillData + * @param code + */ +void generateHFile(const std::string outputPath, const std::string outputFileName, const skillDataStr skillData, hCodeStr code); -void generateCppFile(const std::string, const std::string, const skillDataStr, cppCodeStr); +/** + * @brief Generate the cpp file + * + * @param outputPath + * @param outputFileName + * @param skillData + * @param code + */ +void generateCppFile(const std::string outputPath, const std::string outputFileName, const skillDataStr skillData, cppCodeStr code); +/** + * @brief Print the help message + * + */ void print_help(); +/** + * @brief Generator function + * + * @param fileData + * @return true + * @return false + */ bool generator(fileDataStr fileData); diff --git a/code/include/utils.h b/code/include/utils.h index 9182b98..83b56c7 100644 --- a/code/include/utils.h +++ b/code/include/utils.h @@ -9,8 +9,26 @@ #include #include -void turnToSnakeCase(const std::string, std::string&); +/** + * @brief Convert string to snake case + * + * @param input + * @param output + */ +void turnToSnakeCase(const std::string input, std::string& output); -void getDataTypePath(const std::string, std::string&); +/** + * @brief Get data type path from data type name (e.g. from "sensor_msgs::msg::BatteryState" to "sensor_msgs/msg/battery_state") + * + * @param input + * @param output + */ +void getDataTypePath(const std::string input, std::string& output); -void getPath(const std::string, std::string&); +/** + * @brief Get the path + * + * @param filePath + * @param output + */ +void getPath(const std::string filePath, std::string& output); diff --git a/code/src/utils.cpp b/code/src/utils.cpp index 0660e4e..634d41b 100644 --- a/code/src/utils.cpp +++ b/code/src/utils.cpp @@ -54,6 +54,12 @@ void getDataTypePath(const std::string input, std::string& output) turnToSnakeCase(temp, output); } +/** + * @brief Get the path + * + * @param filePath + * @param output + */ void getPath(const std::string filePath, std::string& output) { // searching for the second to last appearance of '/' to get the path size_t pos = filePath.find_last_of('/');