Minor code cleanup

src/class_diagram/visitor/translation_unit_visitor.h

@@ -38,6 +38,12 @@ using found_relationships_t =
     std::vector<std::pair<clanguml::common::model::diagram_element::id_t,
         common::model::relationship_t>>;
 
+/**
+ * @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<translation_unit_visitor>,
       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:

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 <typename T> 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 <typename T> id_t to_id(const T &declaration);
 
 template <> id_t to_id(const std::string &full_name);

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 <typename ConfigType, typename DiagramType> 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 <typename C, typename D>
     friend std::ostream &operator<<(std::ostream &os, const generator<C, D> &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<std::string> &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 <typename E>
     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:

src/common/visitor/translation_unit_visitor.h

@@ -35,30 +35,71 @@ using found_relationships_t =
     std::vector<std::pair<clanguml::common::model::diagram_element::id_t,
         common::model::relationship_t>>;
 
+/**
+ * @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::comment_visitor> comment_visitor_;

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
+ * Print list of diagrams available in the configuration file
-///
+ *
-/// \param cfg Configuration instance loaded from 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
+ * Check if diagram output directory exists, if not create it
-///
+ *
-/// \param dir Path to the output directory
+ * @param dir Path to the output directory
-/// \return True if directory exists or has been created
+ * @return True if directory exists or has been created
-///
+ */
 bool ensure_output_directory_exists(const std::string &dir);
 
-///
+/**
-/// Generate specific diagram identified by name
+ * Generate specific diagram identified by name
-///
+ *
-/// \param od Diagram output directory
+ * @param od Diagram output directory
-/// \param name Name of the diagram as specified in the config file
+ * @param name Name of the diagram as specified in the config file
-/// \param diagram Diagram model instance
+ * @param diagram Diagram model instance
-/// \param db Compilation database
+ * @param db Compilation database
-/// \param translation_units List of translation units to be used for this
+ * @param translation_units List of translation units to be used for this
-///        diagram
+ *        diagram
-/// \param verbose Logging level
+ * @param verbose Logging level
-///
+ */
 void generate_diagram(const std::string &od, const std::string &name,
     std::shared_ptr<clanguml::config::diagram> diagram,
     const clang::tooling::CompilationDatabase &db,
     const std::vector<std::string> &translation_units, bool verbose);
 
-///
+/**
-/// Find translation units for diagrams.
+ * Find translation units for diagrams.
-///
+ *
-/// For each diagram to be generated, this function selects translation units
+ *  For each diagram to be generated, this function selects translation units
-/// to be used for this diagram. The files are selected as an intersection
+ *  to be used for this diagram. The files are selected as an intersection
-/// between all translation units found in the compilation database and the
+ *  between all translation units found in the compilation database and the
-/// `glob` patterns specified for each diagram in the configuration file.
+ *  `glob` patterns specified for each diagram in the configuration file.
-///
+ *
-/// \param diagram_names List of diagram names to be generated
+ *  @param diagram_names List of diagram names to be generated
-/// \param config Configuration instance
+ *  @param config Configuration instance
-/// \param compilation_database_files All translation units in compilation
+ *  @param compilation_database_files All translation units in compilation
-/// database
+ *  database
-/// \param translation_units_map The output map containing translation
+ *  @param translation_units_map The output map containing translation
-///                 units for each diagram by name
+ *                  units for each diagram by name
-///
+ */
 void find_translation_units_for_diagrams(
     const std::vector<std::string> &diagram_names,
     clanguml::config::config &config,
     const std::vector<std::string> &compilation_database_files,
     std::map<std::string, std::vector<std::string>> &translation_units_map);
 
-///
+/**
-/// Generate diagrams.
+ *  Generate diagrams.
-///
+ *
-/// This function generates all diagrams specified in the configuration file
+ *  This function generates all diagrams specified in the configuration file
-/// and in the command line.
+ *  and in the command line.
-///
+ *
-/// \param diagram_names List of diagram names to be generated
+ *  @param diagram_names List of diagram names to be generated
-/// \param config Configuration instance
+ *  @param config Configuration instance
-/// \param od Output directory where diagrams should be written
+ *  @param od Output directory where diagrams should be written
-/// \param db Compilation database instance
+ *  @param db Compilation database instance
-/// \param verbose Verbosity level
+ *  @param verbose Verbosity level
-/// \param thread_count Number of diagrams to be generated in parallel
+ *  @param thread_count Number of diagrams to be generated in parallel
-/// \param translation_units_map List of translation units to be used for each
+ *  @param translation_units_map List of translation units to be used for each
-///        diagram
+ *         diagram
-///
+ */
 void generate_diagrams(const std::vector<std::string> &diagram_names,
     clanguml::config::config &config, const std::string &od,
     const std::unique_ptr<clang::tooling::CompilationDatabase> &db,

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<clang::FunctionType>()) {
-
+        // TODO
-        //        for (const auto &param_type :
-        //            arg.getAsType()->getAs<clang::FunctionProtoType>()->param_types())
-        //            {
-        //
-        //            if (!param_type->getAs<clang::RecordType>())
-        //                continue;
-        //
-        //            auto classTemplateSpecialization =
-        //                llvm::dyn_cast<clang::ClassTemplateSpecializationDecl>(
-        //                    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<clang::RecordType>(),
-        //                        diagram().should_include(
-        //                            full_template_specialization_name)
-        //                            ?
-        //                            std::make_optional(&template_instantiation)
-        //                            : parent);
-        //            }
-        //        }
     }
     else if (arg.getAsType()->getAs<clang::TemplateSpecializationType>()) {
         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<clang::TemplateSpecializationType>(),
-        //            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<char>' should
         // be simply 'std::string')

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: