From c49517925e6573fb64a81f2acf01799fecf358e1 Mon Sep 17 00:00:00 2001 From: Bartek Kryza Date: Sat, 24 Jun 2023 20:53:41 +0200 Subject: [PATCH] Update Doxygen docs for package_diagram namespace --- .../visitor/translation_unit_visitor.h | 2 +- .../json/package_diagram_generator.h | 39 ++++-- .../plantuml/package_diagram_generator.h | 38 +++++- src/package_diagram/model/diagram.h | 102 ++++++++++++++- .../visitor/translation_unit_visitor.cc | 13 ++ .../visitor/translation_unit_visitor.h | 117 +++++++++++++++++- 6 files changed, 286 insertions(+), 25 deletions(-) diff --git a/src/class_diagram/visitor/translation_unit_visitor.h b/src/class_diagram/visitor/translation_unit_visitor.h index a5ddec96..addbe3ed 100644 --- a/src/class_diagram/visitor/translation_unit_visitor.h +++ b/src/class_diagram/visitor/translation_unit_visitor.h @@ -57,7 +57,7 @@ using clanguml::common::model::template_trait; /** * @brief Class diagram translation unit visitor * - * This class implements the @link clang::RecursiveASTVisitor interface + * This class implements the `clang::RecursiveASTVisitor` interface * for selected visitors relevant to generating class diagrams. */ class translation_unit_visitor diff --git a/src/package_diagram/generators/json/package_diagram_generator.h b/src/package_diagram/generators/json/package_diagram_generator.h index 0e9990da..5c05faa3 100644 --- a/src/package_diagram/generators/json/package_diagram_generator.h +++ b/src/package_diagram/generators/json/package_diagram_generator.h @@ -31,10 +31,7 @@ #include #include -namespace clanguml { -namespace package_diagram { -namespace generators { -namespace json { +namespace clanguml::package_diagram::generators::json { using diagram_config = clanguml::config::package_diagram; using diagram_model = clanguml::package_diagram::model::diagram; @@ -47,21 +44,41 @@ using clanguml::common::model::package; using clanguml::common::model::relationship_t; using namespace clanguml::util; +/** + * @brief Package diagram JSON 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 package `p` + * + * @param p Diagram element + * @param parent JSON node + */ void generate_relationships(const package &p, nlohmann::json &parent) const; - void generate(const package &e, nlohmann::json &parent) const; - - void generate(std::ostream &ostr) const override; + /** + * @brief Generate diagram package + * + * @param p Diagram package element + * @param parent Parent JSON node + */ + void generate(const package &p, nlohmann::json &parent) const; private: mutable nlohmann::json json_; }; -} // namespace json -} // namespace generators -} // namespace package_diagram -} // namespace clanguml +} // namespace clanguml::package_diagram::generators::json diff --git a/src/package_diagram/generators/plantuml/package_diagram_generator.h b/src/package_diagram/generators/plantuml/package_diagram_generator.h index 6ebf8b93..d94cf82a 100644 --- a/src/package_diagram/generators/plantuml/package_diagram_generator.h +++ b/src/package_diagram/generators/plantuml/package_diagram_generator.h @@ -48,18 +48,44 @@ using clanguml::common::model::package; using clanguml::common::model::relationship_t; using namespace clanguml::util; +/** + * @brief Package diagram PlantUML generator + */ class generator : public common_generator { public: generator(diagram_config &config, diagram_model &model); - void generate_alias(const package &c, std::ostream &ostr) const; - - void generate_relationships(const package &p, std::ostream &ostr) const; - - void generate(const package &e, std::ostream &ostr) 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 package `p` + * + * @param p Diagram element + * @param parent Output stream + */ + void generate_relationships(const package &p, std::ostream &ostr) const; + + /** + * @brief Generate diagram package element + * + * @param p Package diagram element + * @param parent Output stream + */ + void generate(const package &e, std::ostream &ostr) const; + + /** + * @brief Generate package elements grouped using `together` PlantUML tag + * + * @param ostr Output stream + */ void generate_groups(std::ostream &ostr) const; private: diff --git a/src/package_diagram/model/diagram.h b/src/package_diagram/model/diagram.h index 3f7f43c1..459e71ea 100644 --- a/src/package_diagram/model/diagram.h +++ b/src/package_diagram/model/diagram.h @@ -31,6 +31,9 @@ using clanguml::common::model::diagram_element; using clanguml::common::model::package; using clanguml::common::model::path; +/** + * @brief Package diagram model. + */ class diagram : public clanguml::common::model::diagram, public clanguml::common::model::element_view, public clanguml::common::model::nested_trait< @@ -44,24 +47,88 @@ public: diagram &operator=(const diagram &) = delete; diagram &operator=(diagram &&) = default; + /** + * @brief Get the diagram model type - in this case package. + * + * @return Type of package diagram. + */ common::model::diagram_t type() const override; + /** + * @brief Get list of references to packages in the diagram model. + * + * @return List of references to packages in the diagram model. + */ const common::reference_vector &packages() const; + /** + * @brief Search for element in the diagram by fully qualified name. + * + * @param full_name Fully qualified element name. + * @return Optional reference to a diagram element. + */ opt_ref 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 Find an element in the diagram by name. + * + * This method allows for typed search, where the type of searched for + * element is determined from template specialization. + * + * @tparam ElementT Type of element (e.g. package) + * @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 template specialization. + * + * @tparam ElementT Type of element (e.g. package) + * @param id Id of the element + * @return Optional reference to a diagram element + */ template opt_ref find(diagram_element::id_t id) const; + /** + * @brief Find elements in the diagram by regex pattern. + * + * This method allows for typed search, where the type of searched for + * element is determined from template specialization. + * + * @tparam ElementT Type of element (e.g. class_) + * @param name String or regex pattern + * @return List of optional references to matched elements. + */ template std::vector> find( const clanguml::common::string_or_regex &pattern) const; + /** + * @brief Add diagram element at nested path + * + * This method handled both diagrams where packages are created from + * namespaces, as well as those were packages are created from project + * subdirectories. + * + * @tparam ElementT Type of diagram element to add + * @param parent_path Package nested path where the element should be added + * @param e Diagram element to add + * @return True, if the element was added. + */ template bool add(const path &parent_path, std::unique_ptr &&e) { @@ -72,16 +139,43 @@ public: return add_with_filesystem_path(parent_path, std::move(e)); } + /** + * @brief Get alias of existing diagram element + * + * @param id Id of a package in the diagram + * @return PlantUML alias of the element + */ + std::string to_alias(diagram_element::id_t id) const; + + /** + * @brief Return the elements JSON context for inja templates. + * + * @return JSON node with elements context. + */ + inja::json context() const override; + +private: + /** + * @brief Add element using namespace as diagram path + * + * @tparam ElementT Element type + * @param e Element to add + * @return True, if the element was added + */ template bool add_with_namespace_path(std::unique_ptr &&e); + /** + * @brief Add element using relative filesystem path as diagram path + * + * @tparam ElementT Element type + * @param parent_path Path to diagram elements parent package + * @param e Element to add + * @return True, if the element was added + */ template bool add_with_filesystem_path( const common::model::path &parent_path, std::unique_ptr &&e); - - std::string to_alias(diagram_element::id_t /*id*/) const; - - inja::json context() const override; }; template diff --git a/src/package_diagram/visitor/translation_unit_visitor.cc b/src/package_diagram/visitor/translation_unit_visitor.cc index 26d1b0b4..964c826f 100644 --- a/src/package_diagram/visitor/translation_unit_visitor.cc +++ b/src/package_diagram/visitor/translation_unit_visitor.cc @@ -592,4 +592,17 @@ bool translation_unit_visitor::find_relationships(const clang::QualType &type, return result; } +clanguml::package_diagram::model::diagram &translation_unit_visitor::diagram() +{ + return diagram_; +} + +const clanguml::config::package_diagram & +translation_unit_visitor::config() const +{ + return config_; +} + +void translation_unit_visitor::finalize() { } + } // namespace clanguml::package_diagram::visitor diff --git a/src/package_diagram/visitor/translation_unit_visitor.h b/src/package_diagram/visitor/translation_unit_visitor.h index 5b937d66..e44eced5 100644 --- a/src/package_diagram/visitor/translation_unit_visitor.h +++ b/src/package_diagram/visitor/translation_unit_visitor.h @@ -37,16 +37,33 @@ using found_relationships_t = std::vector>; +/** + * @brief Package diagram translation unit visitor + * + * This class implements the `clang::RecursiveASTVisitor` interface + * for selected visitors relevant to generating package diagrams. + */ class translation_unit_visitor : public clang::RecursiveASTVisitor, public common::visitor::translation_unit_visitor { public: + /** + * @brief Constructor. + * + * @param sm Current source manager reference + * @param diagram Diagram model + * @param config Diagram configuration + */ translation_unit_visitor(clang::SourceManager &sm, clanguml::package_diagram::model::diagram &diagram, const clanguml::config::package_diagram &config); ~translation_unit_visitor() override = default; + /** + * \defgroup Implementation of ResursiveASTVisitor methods + * @{ + */ virtual bool VisitNamespaceDecl(clang::NamespaceDecl *ns); virtual bool VisitEnumDecl(clang::EnumDecl *decl); @@ -58,48 +75,142 @@ public: virtual bool VisitClassTemplateDecl(clang::ClassTemplateDecl *decl); virtual bool VisitFunctionDecl(clang::FunctionDecl *function_declaration); + /** @} */ - clanguml::package_diagram::model::diagram &diagram() { return diagram_; } + /** + * @brief Get diagram model reference + * + * @return Reference to diagram model created by the visitor + */ + clanguml::package_diagram::model::diagram &diagram(); - const clanguml::config::package_diagram &config() const { return config_; } + /** + * @brief Get diagram model reference + * + * @return Reference to diagram model created by the visitor + */ + const clanguml::config::package_diagram &config() const; - void finalize() { } + /** + * @brief Finalize diagram model + */ + void finalize(); private: + /** + * @brief Get global package id for declaration. + * + * This method calculates package diagram id based on either the namespace + * of the provided declaration or filesystem path of the source file + * where it was declared - depending on the diagram configuration. + * + * This is necessary to infer dependency relationships between packages. + * + * @param cls C++ entity declaration + * @return Id of the package containing that declaration + */ common::model::diagram_element::id_t get_package_id(const clang::Decl *cls); + /** + * @brief Process class declaration + * + * @param cls Class declaration + * @param relationships List of relationships discovered from this class + */ void process_class_declaration( const clang::CXXRecordDecl &cls, found_relationships_t &relationships); + /** + * @brief Process class children + * + * @param cls Class declaration + * @param relationships List of relationships discovered from this class + */ void process_class_children( const clang::CXXRecordDecl &cls, found_relationships_t &relationships); + /** + * @brief Process record children + * + * @param cls Record declaration + * @param relationships List of relationships discovered from this class + */ void process_record_children( const clang::RecordDecl &cls, found_relationships_t &relationships); + /** + * @brief Process record bases + * + * @param cls Class declaration + * @param relationships List of relationships discovered from this class + */ void process_class_bases( const clang::CXXRecordDecl &cls, found_relationships_t &relationships); + /** + * @brief Process method declaration + * + * @param method Method declaration + * @param relationships List of relationships discovered from this method + */ void process_method(const clang::CXXMethodDecl &method, found_relationships_t &relationships); + /** + * @brief Process template method declaration + * + * @param method Method declaration + * @param relationships List of relationships discovered from this method + */ void process_template_method(const clang::FunctionTemplateDecl &method, found_relationships_t &relationships); + /** + * @brief Process member field + * + * @param field_declaration Field declaration + * @param relationships List of relationships discovered from this field + */ void process_field(const clang::FieldDecl &field_declaration, found_relationships_t &relationships); + /** + * @brief Process static member field + * + * @param field_declaration Field declaration + * @param relationships List of relationships discovered from this field + */ void process_static_field(const clang::VarDecl &field_declaration, found_relationships_t &relationships); + /** + * @brief Process friend declaration + * + * @param friend_declaration Field declaration + * @param relationships List of relationships discovered from this friend + */ void process_friend(const clang::FriendDecl &friend_declaration, found_relationships_t &relationships); + /** + * @brief Process type + * + * @param type Reference to some C++ type + * @param relationships List of relationships discovered from this friend + * @param relationship_hint Default relationship type for discovered + * relationships + */ bool find_relationships(const clang::QualType &type, found_relationships_t &relationships, common::model::relationship_t relationship_hint = common::model::relationship_t::kDependency); + /** + * @brief Add discovered relationships for `cls` to the diagram. + * + * @param cls C/C++ entity declaration + * @param relationships List of discovered relationships + */ void add_relationships( clang::Decl *cls, found_relationships_t &relationships);