Minor code cleanup

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_;