From d594f791550627e97b5f272e801388d9e99230c4 Mon Sep 17 00:00:00 2001 From: Bartek Kryza Date: Sat, 24 Jun 2023 20:05:24 +0200 Subject: [PATCH] Update Doxygen docs for include_diagram namespace --- .../json/include_diagram_generator.h | 43 +++++--- .../plantuml/include_diagram_generator.h | 37 +++++-- src/include_diagram/model/diagram.h | 66 +++++++++++++ .../visitor/translation_unit_visitor.cc | 37 +++++-- .../visitor/translation_unit_visitor.h | 98 +++++++++++++++---- 5 files changed, 232 insertions(+), 49 deletions(-) diff --git a/src/include_diagram/generators/json/include_diagram_generator.h b/src/include_diagram/generators/json/include_diagram_generator.h index c446ebe5..e399d438 100644 --- a/src/include_diagram/generators/json/include_diagram_generator.h +++ b/src/include_diagram/generators/json/include_diagram_generator.h @@ -31,10 +31,7 @@ #include #include -namespace clanguml { -namespace include_diagram { -namespace generators { -namespace json { +namespace clanguml::include_diagram::generators::json { using diagram_config = clanguml::config::include_diagram; using diagram_model = clanguml::include_diagram::model::diagram; @@ -48,22 +45,42 @@ using clanguml::common::model::relationship_t; using clanguml::common::model::source_file; using namespace clanguml::util; +/** + * @brief Include diagram JSON generator + */ class generator : public common_generator { public: generator(diagram_config &config, diagram_model &model); - void generate_relationships( - const source_file &p, nlohmann::json &parent) const; - - void generate(const source_file &e, nlohmann::json &parent) const; - + /** + * @brief Main generator method. + * + * This method is called first and coordinates the entire diagram + * generation. + * + * @param ostr Output stream. + */ void generate(std::ostream &ostr) const override; + /** + * @brief Generate relationships originating from source_file `f` + * + * @param p Diagram element + * @param parent JSON node + */ + void generate_relationships( + const source_file &f, nlohmann::json &parent) const; + + /** + * @brief Generate diagram element + * + * @param e Source file diagram element + * @param parent Parent JSON node + */ + void generate(const source_file &e, nlohmann::json &parent) const; + private: mutable nlohmann::json json_; }; -} // namespace json -} // namespace generators -} // namespace include_diagram -} // namespace clanguml +} // namespace clanguml::include_diagram::generators::json diff --git a/src/include_diagram/generators/plantuml/include_diagram_generator.h b/src/include_diagram/generators/plantuml/include_diagram_generator.h index cb193cd1..28742512 100644 --- a/src/include_diagram/generators/plantuml/include_diagram_generator.h +++ b/src/include_diagram/generators/plantuml/include_diagram_generator.h @@ -31,10 +31,7 @@ #include #include -namespace clanguml { -namespace include_diagram { -namespace generators { -namespace plantuml { +namespace clanguml::include_diagram::generators::plantuml { using diagram_config = clanguml::config::include_diagram; using diagram_model = clanguml::include_diagram::model::diagram; @@ -49,18 +46,38 @@ using clanguml::common::model::relationship_t; using clanguml::common::model::source_file; using namespace clanguml::util; +/** + * @brief Include diagram PlantUML generator + */ class generator : public common_generator { public: generator(diagram_config &config, diagram_model &model); + /** + * @brief Main generator method. + * + * This method is called first and coordinates the entire diagram + * generation. + * + * @param ostr Output stream. + */ + void generate(std::ostream &ostr) const override; + + /** + * @brief Generate relationships originating from source_file `f` + * + * @param p Diagram element + * @param parent Output stream + */ void generate_relationships(const source_file &p, std::ostream &ostr) const; + /** + * @brief Generate diagram element + * + * @param e Source file diagram element + * @param parent Output stream + */ void generate(const source_file &e, std::ostream &ostr) const; - - void generate(std::ostream &ostr) const override; }; -} // namespace plantuml -} // namespace generators -} // namespace include_diagram -} // namespace clanguml +} // namespace clanguml::include_diagram::generators::plantuml diff --git a/src/include_diagram/model/diagram.h b/src/include_diagram/model/diagram.h index 47870e66..44bbc996 100644 --- a/src/include_diagram/model/diagram.h +++ b/src/include_diagram/model/diagram.h @@ -32,6 +32,9 @@ using clanguml::common::opt_ref; using clanguml::common::model::diagram_element; using clanguml::common::model::source_file; +/** + * @brief Class representing an include diagram model. + */ class diagram : public clanguml::common::model::diagram, public clanguml::common::model::element_view, public clanguml::common::model::nested_trait get(const std::string &full_name) const override; + /** + * @brief Search for element in the diagram by id. + * + * @param id Element id. + * @return Optional reference to a diagram element. + */ opt_ref get(diagram_element::id_t id) const override; + /** + * @brief Add include diagram element, an include file. + * + * @param f Include diagram element + */ void add_file(std::unique_ptr &&f); + /** + * @brief Find an element in the diagram by name. + * + * This method allows for typed search, where the type of searched for + * element is determined from `ElementT`. + * + * @tparam ElementT Type of element (e.g. source_file) + * @param name Fully qualified name of the element + * @return Optional reference to a diagram element + */ template opt_ref find(const std::string &name) const; + /** + * @brief Find an element in the diagram by id. + * + * This method allows for typed search, where the type of searched for + * element is determined from `ElementT`. + * + * @tparam ElementT Type of element (e.g. source_file) + * @param id Id of the element + * @return Optional reference to a diagram element + */ template opt_ref find(diagram_element::id_t id) const; + /** + * @brief Convert element id to PlantUML alias. + * + * @todo This method does not belong here - refactor to PlantUML specific + * code. + * + * @param full_name Full name of the diagram element. + * @return PlantUML alias. + */ std::string to_alias(const std::string &full_name) const; + /** + * @brief Get list of references to files in the diagram model. + * + * @return List of references to concepts in the diagram model. + */ const common::reference_vector &files() const; + /** + * @brief Find diagram element with a specified name and path. + * + * @param name Name of the element + * @param ns Path relative to the diagram + * @return Optional reference to diagram element, if found. + */ opt_ref get_with_namespace(const std::string &name, const common::model::namespace_ &ns) const override; diff --git a/src/include_diagram/visitor/translation_unit_visitor.cc b/src/include_diagram/visitor/translation_unit_visitor.cc index a538acd9..ccd8b766 100644 --- a/src/include_diagram/visitor/translation_unit_visitor.cc +++ b/src/include_diagram/visitor/translation_unit_visitor.cc @@ -116,12 +116,23 @@ void translation_unit_visitor::include_visitor::InclusionDirective( } } -std::optional -translation_unit_visitor::include_visitor::process_internal_header( +clanguml::include_diagram::model::diagram & +translation_unit_visitor::include_visitor::diagram() +{ + return diagram_; +} + +const clanguml::config::include_diagram & +translation_unit_visitor::include_visitor::config() const +{ + return config_; +} + +void translation_unit_visitor::include_visitor::process_internal_header( const std::filesystem::path &include_path, bool is_system, const common::id_t current_file_id) { - // Relativize the path with respect to relative_to config option + // Make the path relative with respect to relative_to config option auto relative_include_path = include_path; if (config().relative_to) { const std::filesystem::path relative_to{config().relative_to()}; @@ -158,12 +169,9 @@ translation_unit_visitor::include_visitor::process_internal_header( .add_relationship(common::model::relationship{relationship_type, include_file.id(), common::model::access_t::kNone}); } - - return include_file.id(); } -std::optional -translation_unit_visitor::include_visitor::process_external_system_header( +void translation_unit_visitor::include_visitor::process_external_system_header( const std::filesystem::path &include_path, const common::id_t current_file_id) { @@ -187,8 +195,6 @@ translation_unit_visitor::include_visitor::process_external_system_header( common::model::relationship_t::kDependency, f_id, common::model::access_t::kNone}); } - - return f_id; } std::optional @@ -253,4 +259,17 @@ translation_unit_visitor::include_visitor::process_source_file( return {}; } +clanguml::include_diagram::model::diagram &translation_unit_visitor::diagram() +{ + return diagram_; +} + +const clanguml::config::include_diagram & +translation_unit_visitor::config() const +{ + return config_; +} + +void translation_unit_visitor::finalize() { } + } // namespace clanguml::include_diagram::visitor diff --git a/src/include_diagram/visitor/translation_unit_visitor.h b/src/include_diagram/visitor/translation_unit_visitor.h index 5c0760cb..68938c5e 100644 --- a/src/include_diagram/visitor/translation_unit_visitor.h +++ b/src/include_diagram/visitor/translation_unit_visitor.h @@ -35,14 +35,33 @@ namespace clanguml::include_diagram::visitor { +/** + * @brief Include diagram translation unit visitor wrapper + * + * This class implements the @link clang::RecursiveASTVisitor interface, + * for compatibility with other diagram visitors. However, for include + * diagrams this class does not inherit from + * @ref common::visitor::translation_unit_visitor, instead it contains an + * inner class @ref include_visitor, which implements `clang::PPCallbacks` + * interface to handle inclusion directives. + */ class translation_unit_visitor : public clang::RecursiveASTVisitor { public: - // This is an internal class for convenience to be able to access the - // include_visitor type from translation_unit_visitor type + /** + * This is an internal class for convenience to be able to access the + * include_visitor type from translation_unit_visitor type + */ class include_visitor : public clang::PPCallbacks, public common::visitor::translation_unit_visitor { public: + /** + * @brief Constructor. + * + * @param sm Reference to current tu source manager. + * @param diagram Reference to the include diagram model. + * @param config Reference to the diagram configuration. + */ include_visitor(clang::SourceManager &sm, clanguml::include_diagram::model::diagram &diagram, const clanguml::config::include_diagram &config); @@ -73,26 +92,51 @@ public: clang::SrcMgr::CharacteristicKind file_type) override; #endif - std::optional process_internal_header( - const std::filesystem::path &include_path, bool is_system, - common::id_t current_file_id); + /** + * @brief Handle internal header include directive + * + * @param include_path Include path + * @param is_system True, if the path points to a system path + * @param current_file_id File id + */ + void process_internal_header(const std::filesystem::path &include_path, + bool is_system, common::id_t current_file_id); - std::optional process_external_system_header( + /** + * @brief Handle system header include directive + * + * @param include_path Include path + * @param current_file_id File id + */ + void process_external_system_header( const std::filesystem::path &include_path, common::id_t current_file_id); + /** + * @brief Handle a source file + * + * This method allows to process path of the currently visited + * source file. + * + * @param file Absolute path to a source file + * @return Diagram element id, in case the file was added to the diagram + */ std::optional process_source_file( const std::filesystem::path &file); - clanguml::include_diagram::model::diagram &diagram() - { - return diagram_; - } + /** + * @brief Get reference to the include diagram model + * + * @return Reference to the include diagram model + */ + clanguml::include_diagram::model::diagram &diagram(); - const clanguml::config::include_diagram &config() const - { - return config_; - } + /** + * @brief Get reference to the diagram configuration + * + * @return Reference to the diagram configuration + */ + const clanguml::config::include_diagram &config() const; private: // Reference to the output diagram model @@ -102,15 +146,35 @@ public: const clanguml::config::include_diagram &config_; }; + /** + * @brief Constructor + * + * @param sm Reference to the source manager for current tu + * @param diagram Reference to the include diagram model + * @param config Reference to the diagram configuration + */ translation_unit_visitor(clang::SourceManager &sm, clanguml::include_diagram::model::diagram &diagram, const clanguml::config::include_diagram &config); - clanguml::include_diagram::model::diagram &diagram() { return diagram_; } + /** + * @brief Get reference to the include diagram model + * + * @return Reference to the include diagram model + */ + clanguml::include_diagram::model::diagram &diagram(); - const clanguml::config::include_diagram &config() const { return config_; } + /** + * @brief Get reference to the diagram configuration + * + * @return Reference to the diagram configuration + */ + const clanguml::config::include_diagram &config() const; - void finalize() { } + /** + * @brief Run any finalization after traversal is complete + */ + void finalize(); private: // Reference to the output diagram model