diff --git a/src/class_diagram/visitor/translation_unit_visitor.h b/src/class_diagram/visitor/translation_unit_visitor.h index 0e5fafb1..280ce72e 100644 --- a/src/class_diagram/visitor/translation_unit_visitor.h +++ b/src/class_diagram/visitor/translation_unit_visitor.h @@ -38,6 +38,12 @@ using found_relationships_t = std::vector>; +/** + * @brief Class diagram translation unit visitor + * + * This class implements the @link clang::RecursiveASTVisitor interface + * for selected visitors relevant to generating class diagrams. + */ class translation_unit_visitor : public clang::RecursiveASTVisitor, public common::visitor::translation_unit_visitor { @@ -60,10 +66,28 @@ public: virtual bool VisitTypeAliasTemplateDecl(clang::TypeAliasTemplateDecl *cls); + /** + * @brief Get diagram model reference + * + * @return Reference to diagram model created by the visitor + */ clanguml::class_diagram::model::diagram &diagram() { return diagram_; } + /** + * @brief Get diagram config instance + * + * @return Reference to config instance + */ const clanguml::config::class_diagram &config() const { return config_; } + /** + * @brief Finalize diagram model + * + * This method is called after the entire AST has been visited by this + * visitor. It is used to perform necessary post processing on the diagram + * (e.g. resolve translation unit local element ID's into global ID's based + * on elements full names). + */ void finalize(); private: diff --git a/src/common/clang_utils.h b/src/common/clang_utils.h index 5007bf9a..bbd7ff91 100644 --- a/src/common/clang_utils.h +++ b/src/common/clang_utils.h @@ -31,9 +31,22 @@ class NamespaceDecl; } namespace clanguml::common { +/** + * @brief Convert @link clang::AccessSpecifier to @link model::access_t + * + * @param access_specifier Clang member access specifier + * @return Enum value of @link model::access_t + */ model::access_t access_specifier_to_access_t( clang::AccessSpecifier access_specifier); +/** + * @brief Generate full qualified name for @link clang::TagDecl instance + * + * @param declaration Input declaration + * @return String representation including any templates, parameters and + * attribtues + */ std::string get_tag_name(const clang::TagDecl &declaration); template std::string get_qualified_name(const T &declaration) @@ -77,8 +90,30 @@ std::string get_source_text_raw( std::string get_source_text( clang::SourceRange range, const clang::SourceManager &sm); +/** + * @brief Check if an expression is contained in another expression + * + * This method returns true if `sub_stmt` is equal to or is contained in the + * AST subtree of `parent_stmt` + * + * @param parent_stmt Parent statement + * @param sub_stmt Sub statement + * @return + */ bool is_subexpr_of(const clang::Stmt *parent_stmt, const clang::Stmt *sub_stmt); +/** + * @brief Forward template for convertions to ID from various entities + * + * These methods provide the main mechanism for generating globally unique + * identifiers for all elements in the diagrams. The identifiers must be unique + * between different translation units in order for element relationships to + * be properly rendered in diagrams. + * + * @tparam T Type of entity for which ID should be computed + * @param declaration Element (e.g. declaration) for which the ID is needed + * @return Unique ID + */ template id_t to_id(const T &declaration); template <> id_t to_id(const std::string &full_name); diff --git a/src/common/generators/plantuml/generator.h b/src/common/generators/plantuml/generator.h index 7abe0ee4..38851053 100644 --- a/src/common/generators/plantuml/generator.h +++ b/src/common/generators/plantuml/generator.h @@ -41,8 +41,20 @@ std::string to_plantuml(relationship_t r, std::string style); std::string to_plantuml(access_t scope); std::string to_plantuml(message_t r); +/** + * @brief Base class for diagram generators + * + * @tparam ConfigType Configuration type + * @tparam DiagramType Diagram model type + */ template class generator { public: + /** + * @brief Constructor + * + * @param config Reference to instance of @link clanguml::config::diagram + * @param model Reference to instance of @link clanguml::model::diagram + */ generator(ConfigType &config, DiagramType &model) : m_config{config} , m_model{model} @@ -53,22 +65,75 @@ public: virtual ~generator() = default; + /** + * @brief Generate diagram + * + * This method must be implemented in subclasses for specific diagram + * types. It is responsible for calling other methods in appropriate + * order to generate the diagram into the output stream. + * + * @param ostr Output stream + */ virtual void generate(std::ostream &ostr) const = 0; template friend std::ostream &operator<<(std::ostream &os, const generator &g); + /** + * @brief Generate diagram layout hints + * + * This method adds to the diagram any layout hints that were provided + * in the configuration file. + * + * @param ostr Output stream + */ void generate_config_layout_hints(std::ostream &ostr) const; + /** + * @brief Generate PlantUML directives from config file. + * + * This method renders the PlantUML directives provided in the configuration + * file, including resolving any element aliases and Jinja templates. + * + * @param ostr Output stream + * @param directives List of directives from the configuration file + */ void generate_plantuml_directives( std::ostream &ostr, const std::vector &directives) const; + /** + * @brief Generate diagram notes + * + * This method adds any notes in the diagram, which were declared in the + * code using inline directives + * + * @param ostr Output stream + * @param element Element to which the note should be attached + */ void generate_notes( std::ostream &ostr, const model::element &element) const; + /** + * @brief Generate hyper link to element + * + * This method renders links to URL's based on templates provided + * in the configuration file (e.g. Git browser with specific line and + * column offset) + * + * @param ostr Output stream + * @param e Reference to diagram element + * @tparam E Diagram element type + */ template void generate_link(std::ostream &ostr, const E &e) const; + /** + * @brief Update diagram Jinja context + * + * This method updates the diagram context with models properties + * which can be used to render Jinja templates in the diagram (e.g. + * in notes or links) + */ void update_context() const; protected: diff --git a/src/common/visitor/translation_unit_visitor.h b/src/common/visitor/translation_unit_visitor.h index 31a35a63..7aa22355 100644 --- a/src/common/visitor/translation_unit_visitor.h +++ b/src/common/visitor/translation_unit_visitor.h @@ -35,30 +35,71 @@ using found_relationships_t = std::vector>; +/** + * @brief Diagram translation unit visitor base class + * + * This class provides common interface for diagram translation unit + * visitors. + */ class translation_unit_visitor { public: + /** + * @brief Constructor + * + * @param sm Reference to @link clang::SourceManager instance + * @param config Reference to @link clanguml::config::diagram configuration + * instance + */ explicit translation_unit_visitor( clang::SourceManager &sm, const clanguml::config::diagram &config); + /** + * @brief Get clang::SourceManager + * @return Reference to @link clang::SourceManager used by this translation + * unit visitor + */ clang::SourceManager &source_manager() const; protected: + /** + * @brief Set source location in diagram element + * + * @param decl Reference to @link clang::Decl + * @param element Reference to element to be updated + */ void set_source_location(const clang::Decl &decl, clanguml::common::model::source_location &element); + /** + * @brief Set source location in diagram element + * + * @param expr Reference to @link clang::Expr + * @param element Reference to element to be updated + */ void set_source_location(const clang::Expr &expr, clanguml::common::model::source_location &element); + /** + * @brief Set source location in diagram element + * + * @param location Reference to @link clang::SourceLocation + * @param element Reference to element to be updated + */ void set_source_location(const clang::SourceLocation &location, clanguml::common::model::source_location &element); + /** + * @brief Set source location in diagram element + * + * @param decl Reference to @link clang::NamedDecl + * @param element Reference to element to be updated + */ void process_comment(const clang::NamedDecl &decl, clanguml::common::model::decorated_element &e); private: clang::SourceManager &source_manager_; - // Reference to diagram config const clanguml::config::diagram &config_; std::unique_ptr comment_visitor_; diff --git a/src/main.cc b/src/main.cc index e922200d..52fad788 100644 --- a/src/main.cc +++ b/src/main.cc @@ -39,78 +39,78 @@ using namespace clanguml; using config::config; -/// -/// Print the program version and basic information -/// +/** + * Print the program version and basic information + */ void print_version(); -//// -/// Print list of diagrams available in the configuration file -/// -/// \param cfg Configuration instance loaded from configuration file -/// +/** + * Print list of diagrams available in the configuration file + * + * @param cfg Configuration instance loaded from configuration file + */ void print_diagrams_list(const clanguml::config::config &cfg); -/// -/// Check if diagram output directory exists, if not create it -/// -/// \param dir Path to the output directory -/// \return True if directory exists or has been created -/// +/** + * Check if diagram output directory exists, if not create it + * + * @param dir Path to the output directory + * @return True if directory exists or has been created + */ bool ensure_output_directory_exists(const std::string &dir); -/// -/// Generate specific diagram identified by name -/// -/// \param od Diagram output directory -/// \param name Name of the diagram as specified in the config file -/// \param diagram Diagram model instance -/// \param db Compilation database -/// \param translation_units List of translation units to be used for this -/// diagram -/// \param verbose Logging level -/// +/** + * Generate specific diagram identified by name + * + * @param od Diagram output directory + * @param name Name of the diagram as specified in the config file + * @param diagram Diagram model instance + * @param db Compilation database + * @param translation_units List of translation units to be used for this + * diagram + * @param verbose Logging level + */ void generate_diagram(const std::string &od, const std::string &name, std::shared_ptr diagram, const clang::tooling::CompilationDatabase &db, const std::vector &translation_units, bool verbose); -/// -/// Find translation units for diagrams. -/// -/// For each diagram to be generated, this function selects translation units -/// to be used for this diagram. The files are selected as an intersection -/// between all translation units found in the compilation database and the -/// `glob` patterns specified for each diagram in the configuration file. -/// -/// \param diagram_names List of diagram names to be generated -/// \param config Configuration instance -/// \param compilation_database_files All translation units in compilation -/// database -/// \param translation_units_map The output map containing translation -/// units for each diagram by name -/// +/** + * Find translation units for diagrams. + * + * For each diagram to be generated, this function selects translation units + * to be used for this diagram. The files are selected as an intersection + * between all translation units found in the compilation database and the + * `glob` patterns specified for each diagram in the configuration file. + * + * @param diagram_names List of diagram names to be generated + * @param config Configuration instance + * @param compilation_database_files All translation units in compilation + * database + * @param translation_units_map The output map containing translation + * units for each diagram by name + */ void find_translation_units_for_diagrams( const std::vector &diagram_names, clanguml::config::config &config, const std::vector &compilation_database_files, std::map> &translation_units_map); -/// -/// Generate diagrams. -/// -/// This function generates all diagrams specified in the configuration file -/// and in the command line. -/// -/// \param diagram_names List of diagram names to be generated -/// \param config Configuration instance -/// \param od Output directory where diagrams should be written -/// \param db Compilation database instance -/// \param verbose Verbosity level -/// \param thread_count Number of diagrams to be generated in parallel -/// \param translation_units_map List of translation units to be used for each -/// diagram -/// +/** + * Generate diagrams. + * + * This function generates all diagrams specified in the configuration file + * and in the command line. + * + * @param diagram_names List of diagram names to be generated + * @param config Configuration instance + * @param od Output directory where diagrams should be written + * @param db Compilation database instance + * @param verbose Verbosity level + * @param thread_count Number of diagrams to be generated in parallel + * @param translation_units_map List of translation units to be used for each + * diagram + */ void generate_diagrams(const std::vector &diagram_names, clanguml::config::config &config, const std::string &od, const std::unique_ptr &db, diff --git a/src/sequence_diagram/visitor/translation_unit_visitor.cc b/src/sequence_diagram/visitor/translation_unit_visitor.cc index d9abe5cb..ef54740d 100644 --- a/src/sequence_diagram/visitor/translation_unit_visitor.cc +++ b/src/sequence_diagram/visitor/translation_unit_visitor.cc @@ -1549,31 +1549,7 @@ void translation_unit_visitor:: // If this is a nested template type - add nested templates as // template arguments if (arg.getAsType()->getAs()) { - - // for (const auto ¶m_type : - // arg.getAsType()->getAs()->param_types()) - // { - // - // if (!param_type->getAs()) - // continue; - // - // auto classTemplateSpecialization = - // llvm::dyn_cast( - // param_type->getAsRecordDecl()); - // - // if (classTemplateSpecialization) { - // // Read arg info as needed. - // auto nested_template_instantiation = - // build_template_instantiation_from_class_template_specialization( - // *classTemplateSpecialization, - // *param_type->getAs(), - // diagram().should_include( - // full_template_specialization_name) - // ? - // std::make_optional(&template_instantiation) - // : parent); - // } - // } + // TODO } else if (arg.getAsType()->getAs()) { const auto *nested_template_type = @@ -1588,19 +1564,6 @@ void translation_unit_visitor:: argument.set_name(nested_template_name); - // auto nested_template_instantiation = - // build_template_instantiation( - // *arg.getAsType()->getAs(), - // diagram().should_include(full_template_specialization_name) - // ? std::make_optional(&template_instantiation) - // : parent); - // - // argument.set_id(nested_template_instantiation->id()); - // - // for (const auto &t : - // nested_template_instantiation->templates()) - // argument.add_template_param(t); - // Check if this template should be simplified (e.g. system // template aliases such as 'std:basic_string' should // be simply 'std::string') diff --git a/uml/main_sequence_diagram.yml b/uml/main_sequence_diagram.yml index 6f36228d..2f88eaa2 100644 --- a/uml/main_sequence_diagram.yml +++ b/uml/main_sequence_diagram.yml @@ -17,7 +17,6 @@ exclude: # Exclude entities and call expressions from irrelevant files paths: - src/util/util.h -# - src/common/model/enums.h using_namespace: - clanguml plantuml: