Added doxygen comments to common namespace

.clang-uml

@@ -20,6 +20,10 @@ diagrams:
     include!: uml/class/diagram_hierarchy_class.yml
   decorated_element_hierarchy_class:
     include!: uml/class/decorated_element_hierarchy_class.yml
+  stylable_element_hierarchy_class:
+    include!: uml/class/stylable_element_hierarchy_class.yml
+  source_location_hierarchy_class:
+    include!: uml/class/source_location_hierarchy_class.yml
   filter_visitor_hierarchy_class:
     include!: uml/class/filter_visitor_hierarchy_class.yml
   diagram_filter_context_class:
@@ -28,8 +32,16 @@ diagrams:
     include!: uml/class/nested_trait_hierarchy_class.yml
   package_hierarchy_class:
     include!: uml/class/package_hierarchy_class.yml
+  source_file_hierarchy_class:
+    include!: uml/class/source_file_hierarchy_class.yml
+  template_trait_hierarchy_class:
+    include!: uml/class/template_trait_hierarchy_class.yml
+  comment_visitor_hierarchy_class:
+    include!: uml/class/comment_visitor_hierarchy_class.yml
   decorators_class:
     include!: uml/class/decorators_class.yml
+  relationship_context_class:
+    include!: uml/class/relationship_context_class.yml
   common_model_class:
     include!: uml/class/common_model_class.yml
   class_model_class:

src/common/clang_utils.cc

@@ -1,5 +1,5 @@
 /**
- * src/common/visitor/clang_utils.cc
+ * @file src/common/visitor/clang_utils.cc
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/clang_utils.h

@@ -1,5 +1,5 @@
 /**
- * src/common/clang_utils.h
+ * @file src/common/clang_utils.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/compilation_database.cc

@@ -1,5 +1,5 @@
 /**
- * src/common/compilation_database.cc
+ * @file src/common/compilation_database.cc
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/compilation_database.h

@@ -1,5 +1,5 @@
 /**
- * src/common/compilation_database.h
+ * @file src/common/compilation_database.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/generators/generators.cc

@@ -1,5 +1,5 @@
 /**
- * src/common/generators/generators.cc
+ * @file src/common/generators/generators.cc
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/generators/generators.h

@@ -1,5 +1,5 @@
 /**
- * src/common/generators/generators.h
+ * @file src/common/generators/generators.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/generators/json/generator.cc

@@ -1,5 +1,5 @@
 /**
- * src/common/generators/json/generator.cc
+ * @file src/common/generators/json/generator.cc
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/generators/json/generator.h

@@ -1,5 +1,5 @@
 /**
- * src/common/generators/json/generator.h
+ * @file src/common/generators/json/generator.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/generators/nested_element_stack.h

@@ -1,5 +1,5 @@
 /**
- * src/common/generators/nested_element_stack.h
+ * @file src/common/generators/nested_element_stack.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *
@@ -38,6 +38,9 @@ public:
         current_level_groups_.push_back({});
     }
 
+    /**
+     * Switch to next level in the element stack
+     */
     void enter()
     {
         if (!is_flat_)
@@ -46,6 +49,9 @@ public:
         current_level_groups_.push_back({});
     }
 
+    /**
+     * Switch to previous level in the element stack
+     */
     void leave()
     {
         if (!is_flat_)
@@ -54,16 +60,30 @@ public:
         current_level_groups_.pop_back();
     }
 
+    /**
+     * Add element pointer to a specified group at the current level
+     */
     void group_together(const std::string &group_name, T *e)
     {
         current_level_groups_[current_level_][group_name].push_back(e);
     }
 
+    /**
+     * Get map of element groups at the current level.
+     *
+     * @return Reference to element groups.
+     */
     const std::map<std::string, std::vector<T *>> &get_current_groups()
     {
         return current_level_groups_.at(current_level_);
     }
 
+    /**
+     * Get element group by name - the group must exist at the current level.
+     *
+     * @param group_name Element group name
+     * @return
+     */
     const std::vector<T *> &get_group(const std::string &group_name)
     {
         return get_current_groups().at(group_name);

src/common/generators/plantuml/generator.cc

@@ -1,5 +1,5 @@
 /**
- * src/common/generators/plantuml/generator.h
+ * @file src/common/generators/plantuml/generator.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/generators/plantuml/generator.h

@@ -1,5 +1,5 @@
 /**
- * src/common/generators/plantuml/generator.h
+ * @file src/common/generators/plantuml/generator.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/generators/progress_indicator.cc

@@ -1,5 +1,5 @@
 /**
- * src/common/generators/progress_indicator.cc
+ * @file src/common/generators/progress_indicator.cc
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/generators/progress_indicator.h

@@ -1,5 +1,5 @@
 /**
- * src/common/generators/progress_indicator.h
+ * @file src/common/generators/progress_indicator.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *
@@ -25,6 +25,9 @@
 
 namespace clanguml::common::generators {
 
+/**
+ * @brief Container for diagram generation progress indicators
+ */
 class progress_indicator {
 public:
     struct progress_state {
@@ -42,15 +45,40 @@ public:
 
     progress_indicator();
 
+    /**
+     * Add a new progress bar to the indicator set
+     *
+     * @param name Name (prefix) of the progress bar
+     * @param max Total number of steps in the progress bar
+     * @param color Color of the progress bar
+     */
     void add_progress_bar(
         const std::string &name, size_t max, indicators::Color color);
 
+    /**
+     * Increment specified progress bar.
+     *
+     * @param name Name of the progress bar
+     */
     void increment(const std::string &name);
 
+    /**
+     * Stop all the progress bars.
+     */
     void stop();
 
+    /**
+     * Set specified progress bar as complete.
+     *
+     * @param name Name of the progress bar
+     */
     void complete(const std::string &name);
 
+    /**
+     * Set progress bar as failed.
+     *
+     * @param name Name of the progress bar
+     */
     void fail(const std::string &name);
 
 private:

src/common/model/decorated_element.cc

@@ -1,5 +1,5 @@
 /**
- * src/class_diagram/model/decorated_element.cc
+ * @file src/class_diagram/model/decorated_element.cc
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/model/decorated_element.h

@@ -1,5 +1,5 @@
 /**
- * src/class_diagram/model/decorated_element.h
+ * @file src/class_diagram/model/decorated_element.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/model/diagram.cc

@@ -1,5 +1,5 @@
 /**
- * src/common/model/diagram.cc
+ * @file src/common/model/diagram.cc
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/model/diagram.h

@@ -1,5 +1,5 @@
 /**
- * src/common/model/diagram.h
+ * @file src/common/model/diagram.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/model/diagram_element.cc

@@ -1,5 +1,5 @@
 /**
- * src/common/model/diagram_element.cc
+ * @file src/common/model/diagram_element.cc
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/model/diagram_filter.cc

@@ -1,5 +1,5 @@
 /**
- * src/common/model/diagram_filter.cc
+ * @file src/common/model/diagram_filter.cc
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/model/diagram_filter.h

@@ -1,5 +1,5 @@
 /**
- * src/common/model/diagram_filter.h
+ * @file src/common/model/diagram_filter.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/model/element.cc

@@ -1,5 +1,5 @@
 /**
- * src/common/model/element.cc
+ * @file src/common/model/element.cc
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/model/element.h

@@ -1,5 +1,5 @@
 /**
- * src/common/model/element.h
+ * @file src/common/model/element.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/model/element_view.h

@@ -1,5 +1,5 @@
 /**
- * src/common/model/element_view.h
+ * @file src/common/model/element_view.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/model/enums.cc

@@ -1,5 +1,5 @@
 /**
- * src/common/model/enums.cc
+ * @file src/common/model/enums.cc
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/model/enums.h

@@ -1,5 +1,5 @@
 /**
- * src/common/model/enums.h
+ * @file src/common/model/enums.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/model/namespace.cc

@@ -1,5 +1,5 @@
 /**
- * src/common/model/namespace.cc
+ * @file src/common/model/namespace.cc
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/model/namespace.h

@@ -1,5 +1,5 @@
 /**
- * src/common/model/namespace.h
+ * @file src/common/model/namespace.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/model/nested_trait.h

@@ -1,5 +1,5 @@
 /**
- * src/common/model/nested_trait.h
+ * @file src/common/model/nested_trait.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/model/package.cc

@@ -1,5 +1,5 @@
 /**
- * src/common/model/package.cc
+ * @file src/common/model/package.cc
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/model/package.h

@@ -1,5 +1,5 @@
 /**
- * src/common/model/package.h
+ * @file src/common/model/package.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/model/path.h

@@ -1,5 +1,5 @@
 /**
- * src/common/model/path.h
+ * @file src/common/model/path.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *
@@ -25,10 +25,30 @@
 
 namespace clanguml::common::model {
 
-enum class path_type { kNamespace, kFilesystem };
+/**
+ * @brief Type of diagram path
+ *
+ * Paths in diagrams represent the nest structure within a diagram, e.g.
+ * a nested set of namespaces or nested set of directories.
+ */
+enum class path_type {
+    kNamespace, /*!< Namespace path */
+    kFilesystem /*!< Filesystem path */
+};
 
+/**
+ * @brief Diagram path
+ *
+ * This class stores a diagram path, such as a namespace or directory
+ * structure.
+ */
 class path {
 
+    /**
+     * Returns the path separator based on the path type.
+     *
+     * @return Path separator
+     */
     const char *separator() const
     {
         switch (path_type_) {
@@ -133,15 +153,36 @@ public:
         return left.to_string() < right.to_string();
     }
 
+    /**
+     * Render the path as string.
+     *
+     * @return  String representation of the path.
+     */
     std::string to_string() const
     {
         return fmt::format("{}", fmt::join(path_, std::string{separator()}));
     }
 
+    /**
+     * Whether the path is empty.
+     *
+     * @return
+     */
     bool is_empty() const { return path_.empty(); }
 
+    /**
+     * Return the number of elements in the path.
+     *
+     * @return Size of path.
+     */
     size_t size() const { return path_.size(); }
 
+    /**
+     * Append path to path.
+     *
+     * @param right Path to append at the end.
+     * @return New merged path.
+     */
     path operator|(const path &right) const
     {
         path res{*this};
@@ -149,8 +190,18 @@ public:
         return res;
     }
 
+    /**
+     * Append path to the current path.
+     *
+     * @param right
+     */
     void operator|=(const path &right) { append(right); }
 
+    /**
+     * Append path element to path.
+     *
+     * @return New path.
+     */
     path operator|(const std::string &right) const
     {
         path res{*this};
@@ -158,6 +209,11 @@ public:
         return res;
     }
 
+    /**
+     * Append path element to the current path.
+     *
+     * @param right Path element to append.
+     */
     void operator|=(const std::string &right) { append(right); }
 
     std::string &operator[](const unsigned int index) { return path_[index]; }
@@ -167,8 +223,18 @@ public:
         return path_[index];
     }
 
-    void append(const std::string &ns) { path_.push_back(ns); }
+    /**
+     * Append path element to path.
+     *
+     * @return New path.
+     */
+    void append(const std::string &name) { path_.push_back(name); }
 
+    /**
+     * Append path to current path.
+     *
+     * @param ns Path to append.
+     */
     void append(const path &ns)
     {
         for (const auto &n : ns) {
@@ -176,6 +242,9 @@ public:
         }
     }
 
+    /**
+     * Drop the last element of the path.
+     */
     void pop_back()
     {
         if (!path_.empty()) {
@@ -183,6 +252,11 @@ public:
         }
     }
 
+    /**
+     * Get the parent of the last element in the path.
+     *
+     * @return Path to the parent of the last element, or nullopt.
+     */
     std::optional<path> parent() const
     {
         if (size() <= 1) {
@@ -194,16 +268,34 @@ public:
         return {std::move(res)};
     }
 
-    bool starts_with(const path &right) const
+    /**
+     * Returns true if path starts with specified prefix.
+     * @param prefix Path prefix to check.
+     * @return
+     */
+    bool starts_with(const path &prefix) const
     {
-        return util::starts_with(path_, right.path_);
+        return util::starts_with(path_, prefix.path_);
     }
 
-    bool ends_with(const path &right) const
+    /**
+     * Returns true if path ends with suffix
+     * @param suffix Path suffix to check
+     * @return
+     */
+    bool ends_with(const path &suffix) const
     {
-        return util::ends_with(path_, right.path_);
+        return util::ends_with(path_, suffix.path_);
     }
 
+    /**
+     * @brief Returns the common prefix of 2 paths.
+     *
+     * If no common prefix exists between 2 paths, the result is an empty path.
+     *
+     * @param right Path to compare
+     * @return Common path prefix
+     */
     path common_path(const path &right) const
     {
         path res{};
@@ -216,6 +308,14 @@ public:
         return res;
     }
 
+    /**
+     * Make the current path relative to the other path, if possible.
+     *
+     * If not, return the original path.
+     *
+     * @param right Parent path
+     * @return Path relative to `right`
+     */
     path relative_to(const path &right) const
     {
         path res{*this};
@@ -226,15 +326,21 @@ public:
         return res;
     }
 
-    std::string relative(const std::string &name) const
+    /**
+     * Make path represented as a string relative to the current path.
+     *
+     * @param ns Path to make relative against *this.
+     * @return Relative path.
+     */
+    std::string relative(const std::string &ns) const
     {
         if (is_empty())
-            return name;
+            return ns;
 
-        if (name == to_string())
+        if (ns == to_string())
-            return name;
+            return ns;
 
-        auto res = name;
+        auto res = ns;
         auto ns_prefix = to_string() + std::string{separator()};
 
         auto it = res.find(ns_prefix);
@@ -246,6 +352,11 @@ public:
         return res;
     }
 
+    /**
+     * Return the name of the last element in the path.
+     *
+     * @return Name of the last element in the path.
+     */
     std::string name() const
     {
         assert(size() > 0);
@@ -265,6 +376,11 @@ public:
     path::container_type::const_iterator begin() const { return path_.begin(); }
     path::container_type::const_iterator end() const { return path_.end(); }
 
+    /**
+     * Get path type.
+     *
+     * @return Path type.
+     */
     path_type type() const { return path_type_; }
 
 private:

src/common/model/relationship.cc

@@ -1,5 +1,5 @@
 /**
- * src/common/model/relationship.cc
+ * @file src/common/model/relationship.cc
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/model/relationship.h

@@ -1,5 +1,5 @@
 /**
- * src/common/model/relationship.h
+ * @file src/common/model/relationship.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *
@@ -25,9 +25,28 @@
 
 namespace clanguml::common::model {
 
+/**
+ * @brief Class representing any relationship other than inheritance
+ *
+ * This class represents all kinds of relationships between diagram elements,
+ * except for inheritance which are handled in a special way
+ * (See @ref clanguml::class_diagram::model::class_parent).
+ *
+ * @embed{relationship_context_class.svg}
+ */
 class relationship : public common::model::decorated_element,
                      public common::model::stylable_element {
 public:
+    /**
+     * Constructor.
+     *
+     * @param type Type of relationship
+     * @param destination Id of the relationship target
+     * @param access Access scope of the relationship
+     * @param label Relationship label
+     * @param multiplicity_source Multiplicity at the source
+     * @param multiplicity_destination Multiplicity at the destination
+     */
     relationship(relationship_t type, int64_t destination,
         access_t access = access_t::kPublic, std::string label = "",
         std::string multiplicity_source = "",
@@ -35,23 +54,90 @@ public:
 
     virtual ~relationship() = default;
 
+    /**
+     * Set the type of relatinoship.
+     *
+     * @param type Type of relationship.
+     */
     void set_type(relationship_t type) noexcept;
+
+    /**
+     * Get the type of relatinoship.
+     *
+     * @return Type of relationship.
+     */
     relationship_t type() const noexcept;
 
+    /**
+     * Set id of the diagram element which is the target of this
+     * relationship.
+     *
+     * @param destination Target element id.
+     */
     void set_destination(int64_t destination);
+
+    /**
+     * Get the id of the target element of this relationship.
+     *
+     * @return Target element id.
+     */
     clanguml::common::id_t destination() const;
 
+    /**
+     * Set the relationship multiplicity at the source.
+     *
+     * @param multiplicity_source Source multiplicity.
+     */
     void set_multiplicity_source(const std::string &multiplicity_source);
+
+    /**
+     * Set the relationship multiplicity at the source.
+     *
+     * @return Source multiplicity.
+     */
     std::string multiplicity_source() const;
 
+    /**
+     * Set the relationship multiplicity at the destination.
+     *
+     * @param multiplicity_destination Destination multiplicity.
+     */
     void set_multiplicity_destination(
         const std::string &multiplicity_destination);
+
+    /**
+     * Set the relationship multiplicity at the destination.
+     *
+     * @return Destination multiplicity.
+     */
     std::string multiplicity_destination() const;
 
+    /**
+     * Set relationship label.
+     *
+     * @param label Relationship label.
+     */
     void set_label(const std::string &label);
+
+    /**
+     * Get the relationship label.
+     *
+     * @return Relationoship label.
+     */
     std::string label() const;
 
+    /**
+     * Set the access scope for this relationship (e.g `public`)
+     *
+     * @param scope Access scope
+     */
     void set_access(access_t scope) noexcept;
+
+    /**
+     * Get the relationship access scope (e.g. `public`).
+     *
+     * @return Access scope
+     */
     access_t access() const noexcept;
 
     friend bool operator==(const relationship &l, const relationship &r);

src/common/model/source_file.cc

@@ -1,5 +1,5 @@
 /**
- * src/common/model/source_file.cc
+ * @file src/common/model/source_file.cc
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/model/source_file.h

@@ -1,5 +1,5 @@
 /**
- * src/common/model/source_file.h
+ * @file src/common/model/source_file.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *
@@ -34,7 +34,14 @@
 
 namespace clanguml::common::model {
 
-enum class source_file_t { kDirectory, kHeader, kImplementation };
+/**
+ * This enum represents different kinds of files in the diagram.
+ */
+enum class source_file_t {
+    kDirectory,     /*!< Diagram element is a directory */
+    kHeader,        /*!< Diagram element is a header */
+    kImplementation /*!< Diagram element is a source file (e.g. cpp) */
+};
 
 std::string to_string(source_file_t sf);
 
@@ -48,6 +55,11 @@ struct fs_path_sep {
 
 using filesystem_path = common::model::path;
 
+/**
+ * @brief Diagram element representing some file or directory.
+ *
+ * @embed{source_file_hierarchy_class.svg}
+ */
 class source_file
     : public common::model::diagram_element,
       public common::model::stylable_element,
@@ -66,16 +78,6 @@ public:
         set_id(common::to_id(preferred));
     }
 
-    void set_path(const filesystem_path &p) { path_ = p; }
-
-    void set_absolute() { is_absolute_ = true; }
-
-    bool is_absolute() const { return is_absolute_; }
-
-    void set_type(source_file_t type) { type_ = type; }
-
-    source_file_t type() const { return type_; }
-
     source_file(const source_file &) = delete;
     source_file(source_file &&) = default;
     source_file &operator=(const source_file &) = delete;
@@ -87,15 +89,64 @@ public:
             (type_ == right.type_);
     }
 
+    /**
+     * Set the path to the element in the diagram.
+     *
+     * @param p Diagram path.
+     */
+    void set_path(const filesystem_path &p) { path_ = p; }
+
+    /**
+     * Is the elements path absolute?
+     *
+     * @return True if the elements path is absolute.
+     */
+    bool is_absolute() const { return is_absolute_; }
+
+    /**
+     * Set the type of the source file.
+     *
+     * @param type Type of the source file.
+     */
+    void set_type(source_file_t type) { type_ = type; }
+
+    /**
+     * Get the source file elements type.
+     *
+     * @return Type of the source file.
+     */
+    source_file_t type() const { return type_; }
+
+    /**
+     * Get the source file's parent path.
+     *
+     * @return Source file parent path.
+     */
     const filesystem_path &path() const { return path_; }
 
+    /**
+     * Return the full path string, i.e. parent path and elements name.
+     *
+     * @return Full source file path as string.
+     */
     std::string full_name(bool /*relative*/) const override
     {
         return (path_ | name()).to_string();
     }
 
+    /**
+     * Return full path, i.e. parent path and elements name.
+     *
+     * @return Full source file path.
+     */
     auto full_path() const { return path() | name(); }
 
+    /**
+     * Convert the source file path to std::filesystem::path, relative to `base`
+     *
+     * @param base Base path
+     * @return Filesystem path to the source file.
+     */
     std::filesystem::path fs_path(const std::filesystem::path &base = {}) const
     {
         std::filesystem::path res;
@@ -114,6 +165,11 @@ public:
         return res.lexically_normal();
     }
 
+    /**
+     * Return inja context for this element.
+     *
+     * @return Inja context.
+     */
     inja::json context() const override
     {
         inja::json ctx = diagram_element::context();

src/common/model/source_location.cc

@@ -1,5 +1,5 @@
 /**
- * src/common/model/source_location.cc
+ * @file src/common/model/source_location.cc
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/model/source_location.h

@@ -1,5 +1,5 @@
 /**
- * src/common/model/source_location.h
+ * @file src/common/model/source_location.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *
@@ -24,6 +24,8 @@ namespace clanguml::common::model {
 
 /**
  * @brief Base class of all diagram elements that have source location.
+ *
+ * @embed{source_location_hierarchy_class.svg}
  */
 class source_location {
 public:

src/common/model/stylable_element.cc

@@ -1,5 +1,5 @@
 /**
- * src/common/model/stylable_element.cc
+ * @file src/common/model/stylable_element.cc
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/model/stylable_element.h

@@ -1,5 +1,5 @@
 /**
- * src/common/model/stylable_element.h
+ * @file src/common/model/stylable_element.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *
@@ -21,9 +21,25 @@
 
 namespace clanguml::common::model {
 
+/**
+ * @brief Diagram elements to which style can be applied.
+ *
+ * @embed{stylable_element_hierarchy_class.svg}
+ */
 class stylable_element {
 public:
+    /**
+     * Set style.
+     *
+     * @param style Style specification
+     */
     void set_style(const std::string &style);
+
+    /**
+     * Get style
+     *
+     * @return Style specification
+     */
     std::string style() const;
 
 private:

src/common/model/template_parameter.cc

@@ -1,5 +1,5 @@
 /**
- * src/common/model/template_parameter.cc
+ * @file src/common/model/template_parameter.cc
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *
@@ -209,6 +209,8 @@ std::optional<std::string> template_parameter::name() const
 
 void template_parameter::set_default_value(const std::string &value)
 {
+    assert(kind_ != template_parameter_kind_t::argument);
+
     default_value_ = value;
 }
 
@@ -649,10 +651,6 @@ void template_parameter::is_ellipsis(bool e) { is_ellipsis_ = e; }
 
 bool template_parameter::is_ellipsis() const { return is_ellipsis_; }
 
-void template_parameter::is_noexcept(bool e) { is_noexcept_ = e; }
-
-bool template_parameter::is_noexcept() const { return is_noexcept_; }
-
 int calculate_template_params_specialization_match(
     const std::vector<template_parameter> &specialization_params,
     const std::vector<template_parameter> &template_params)

src/common/model/template_trait.cc

@@ -1,5 +1,5 @@
 /**
- * src/common/model/template_trait.cc
+ * @file src/common/model/template_trait.cc
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *
@@ -39,25 +39,11 @@ std::ostream &template_trait::render_template_params(std::ostream &ostr,
     return ostr;
 }
 
-void template_trait::set_base_template(const std::string &full_name)
-{
-    base_template_full_name_ = full_name;
-}
-
-std::string template_trait::base_template() const
-{
-    return base_template_full_name_;
-}
-
 void template_trait::add_template(template_parameter &&tmplt)
 {
     templates_.push_back(std::move(tmplt));
 }
 
-bool template_trait::is_implicit() const { return is_implicit_; }
-
-void template_trait::set_implicit(bool implicit) { is_implicit_ = implicit; }
-
 const std::vector<template_parameter> &template_trait::template_params() const
 {
     return templates_;

src/common/model/template_trait.h

@@ -1,5 +1,5 @@
 /**
- * src/common/model/template_trait.h
+ * @file src/common/model/template_trait.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *
@@ -25,30 +25,52 @@
 
 namespace clanguml::common::model {
 
+/**
+ * @brief Common interface for template diagram elements.
+ *
+ * @embed{template_trait_hierarchy_class.svg}
+ */
 class template_trait {
 public:
+    /**
+     * Render the template parameters to a stream.
+     *
+     * @param ostr Output stream
+     * @param using_namespace Relative to namespace
+     * @param relative Whether to make template arguments relative to
+     *                 `using_namespace`
+     * @return Reference to output stream
+     */
     std::ostream &render_template_params(std::ostream &ostr,
         const common::model::namespace_ &using_namespace, bool relative) const;
 
-    void set_base_template(const std::string &full_name);
+    /**
-
+     * Add template parameter
-    std::string base_template() const;
+     *
-
+     * @param tmplt Template parameter
+     */
     void add_template(template_parameter &&tmplt);
 
+    /**
+     * Get reference to template parameters.
+     *
+     * @return Reference to template parameters list.
+     */
     const std::vector<template_parameter> &template_params() const;
 
+    /**
+     * @brief Wrapper around @ref
+     * calculate_template_params_specialization_match()
+     *
+     * @param other Other template diagram element
+     * @return Match value
+     */
     int calculate_template_specialization_match(
         const template_trait &other) const;
 
-    bool is_implicit() const;
-
-    void set_implicit(bool implicit);
-
 private:
     std::vector<template_parameter> templates_;
     std::string base_template_full_name_;
-    bool is_implicit_{false};
 };
 
 } // namespace clanguml::common::model

src/common/model/tvl.h

@@ -1,5 +1,5 @@
 /**
- * src/class_diagram/model/tvl.h
+ * @file src/class_diagram/model/tvl.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *
@@ -20,10 +20,29 @@
 #include <optional>
 #include <string>
 
+/**
+ * This namespace implements convenience functions to handle 3-value logic
+ * operations needed for applying diagram filters.
+ *
+ * @see clanguml::common::model::diagram_filter
+ * @see clanguml::common::model::filter_visitor
+ */
 namespace clanguml::common::model::tvl {
 
+/**
+ * Alias for 3-value logic values
+ *
+ * If optional holds nullopt, the value is undefined.
+ */
 using value_t = std::optional<bool>;
 
+/**
+ * Calculate 3-value logic AND value.
+ *
+ * @param l Left value
+ * @param r Right value
+ * @return Result of AND operation.
+ */
 inline value_t and_(const value_t &l, const value_t &r)
 {
     if (!l.has_value())
@@ -35,6 +54,13 @@ inline value_t and_(const value_t &l, const value_t &r)
     return r.value() && l.value();
 }
 
+/**
+ * Calculate 3-value logic OR value.
+ *
+ * @param l Left value
+ * @param r Right value
+ * @return Result of OR operation.
+ */
 inline value_t or_(const value_t &l, const value_t &r)
 {
     if (!l.has_value() && !r.has_value())
@@ -49,12 +75,40 @@ inline value_t or_(const value_t &l, const value_t &r)
     return false;
 }
 
+/**
+ * Whether the value holds true
+ *
+ * @param v Logical value
+ * @return True, if v holds true
+ */
 inline bool is_true(const value_t &v) { return v.has_value() && v.value(); }
 
+/**
+ * Whether the value holds false
+ *
+ * @param v Logical value
+ * @return True, if v holds false
+ */
 inline bool is_false(const value_t &v) { return v.has_value() && !v.value(); }
 
+/**
+ * Whether the value is undefined
+ *
+ * @param v Logical value
+ * @return True, if v has no value
+ */
 inline bool is_undefined(const value_t &v) { return !v.has_value(); }
 
+/**
+ * 3-value logic equivalent of std::all_of
+ *
+ * @tparam InputIterator Iterator type
+ * @tparam Predicate Predicate type
+ * @param first First iterator element
+ * @param last Last iterator element
+ * @param pred Predicate to apply to each element
+ * @return True, if all elements are true or undefined
+ */
 template <typename InputIterator, typename Predicate>
 inline value_t all_of(InputIterator first, InputIterator last, Predicate pred)
 {
@@ -76,6 +130,16 @@ inline value_t all_of(InputIterator first, InputIterator last, Predicate pred)
     return res;
 }
 
+/**
+ * 3-value logic equivalent of std::any_of
+ *
+ * @tparam InputIterator Iterator type
+ * @tparam Predicate Predicate type
+ * @param first First iterator element
+ * @param last Last iterator element
+ * @param pred Predicate to apply to each element
+ * @return True, if at least 1 element is true
+ */
 template <typename InputIterator, typename Predicate>
 inline value_t any_of(InputIterator first, InputIterator last, Predicate pred)
 {

src/common/types.cc

@@ -1,5 +1,5 @@
 /**
- * src/common/types.cc
+ * @file src/common/types.cc
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/types.h

@@ -1,5 +1,5 @@
 /**
- * src/common/types.h
+ * @file src/common/types.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/visitor/ast_id_mapper.cc

@@ -1,5 +1,5 @@
 /**
- * src/class_diagram/visitor/ast_id_mapper.cc
+ * @file src/class_diagram/visitor/ast_id_mapper.cc
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/visitor/ast_id_mapper.h

@@ -1,5 +1,5 @@
 /**
- * src/class_diagram/visitor/ast_id_mapper.h
+ * @file src/class_diagram/visitor/ast_id_mapper.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *
@@ -24,14 +24,40 @@
 
 namespace clanguml::common::visitor {
 
+/**
+ * @brief Mapping between Clang AST identifier and `clang-uml` unique ids
+ *
+ * Since identifiers provided by Clang AST are not transferable between
+ * translation units (i.e. the same class can have a different id when visited
+ * from different translation units), we need global identifiers which are
+ * the same among all translation units.
+ *
+ * Currently they are calculated as hashes from the fully qualified string
+ * representation of the type.
+ *
+ * This class allows to store mappings between Clang local identifiers
+ * in current translation unit and the global identifiers for the element.
+ */
 class ast_id_mapper {
 public:
     using id_t = common::model::diagram_element::id_t;
 
     ast_id_mapper() = default;
 
+    /**
+     * Add id mapping.
+     *
+     * @param ast_id Clang's local AST id.
+     * @param global_id Global element id.
+     */
     void add(int64_t ast_id, id_t global_id);
 
+    /**
+     * Get global element id based on it's local Clang AST id, if exists.
+     *
+     * @param ast_id Clang's local AST id.
+     * @return Global id, if exists.
+     */
     std::optional<id_t> get_global_id(int64_t ast_id);
 
 private:

src/common/visitor/comment/clang_visitor.cc

@@ -1,5 +1,5 @@
 /**
- * src/common/visitor/comment/clang_visitor.cc
+ * @file src/common/visitor/comment/clang_visitor.cc
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/visitor/comment/clang_visitor.h

@@ -1,5 +1,5 @@
 /**
- * src/common/visitor/comment/clang_visitor.h
+ * @file src/common/visitor/comment/clang_visitor.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *
@@ -25,10 +25,19 @@
 
 namespace clanguml::common::visitor::comment {
 
+/**
+ * @brief Uses Clang's comment parser to extract Doxygen-style comment blocks.
+ */
 class clang_visitor : public comment_visitor {
 public:
     clang_visitor(clang::SourceManager &source_manager);
 
+    /**
+     * Extracts Doxygen style comment blocks from the comment.
+     *
+     * @param decl Clang's named declaration
+     * @param e Diagram element
+     */
     void visit(const clang::NamedDecl &decl,
         common::model::decorated_element &e) override;
 

src/common/visitor/comment/comment_visitor.cc

@@ -1,5 +1,5 @@
 /**
- * src/common/visitor/comment/comment_visitor.cc
+ * @file src/common/visitor/comment/comment_visitor.cc
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/visitor/comment/comment_visitor.h

@@ -1,5 +1,5 @@
 /**
- * src/common/visitor/comment/comment_visitor.h
+ * @file src/common/visitor/comment/comment_visitor.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *
@@ -24,15 +24,31 @@
 
 namespace clanguml::common::visitor::comment {
 
+/**
+ * @brief Base class for comment visitors
+ *
+ * @embed{comment_visitor_hierarchy_class.svg}
+ */
 class comment_visitor {
 public:
     comment_visitor(clang::SourceManager &source_manager);
 
     virtual ~comment_visitor() = default;
 
+    /**
+     * Visit the comment in `decl` and extract it's contents to the diagram
+     * element.
+     *
+     * @param decl Clang's named declaration
+     * @param e Diagram element
+     */
     virtual void visit(
         const clang::NamedDecl &decl, common::model::decorated_element &e) = 0;
 
+    /**
+     * Return reference to current source manager.
+     * @return Reference to source manager.
+     */
     clang::SourceManager &source_manager();
 
 private:

src/common/visitor/comment/plain_visitor.cc

@@ -1,5 +1,5 @@
 /**
- * src/common/visitor/comment/plain_visitor.cc
+ * @file src/common/visitor/comment/plain_visitor.cc
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/visitor/comment/plain_visitor.h

@@ -1,5 +1,5 @@
 /**
- * src/common/visitor/comment/plain_visitor.h
+ * @file src/common/visitor/comment/plain_visitor.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *
@@ -25,11 +25,22 @@
 
 namespace clanguml::common::visitor::comment {
 
+/**
+ * @brief Plain comment visitor which extracts raw and formatted comment.
+ */
 class plain_visitor : public comment_visitor {
 public:
     plain_visitor(clang::SourceManager &source_manager);
 
+    /**
+     * Extracts 'raw' and 'formatted' comment values from the Clang's
+     * parser.
+     *
+     * @param decl Clang's named declaration
+     * @param e Diagram element
+     */
     void visit(const clang::NamedDecl &decl,
         common::model::decorated_element &e) override;
 };
-}
+
+} // namespace clanguml::common::visitor::comment

src/common/visitor/translation_unit_visitor.cc

@@ -1,5 +1,5 @@
 /**
- * src/common/visitor/translation_unit_visitor.cc
+ * @file src/common/visitor/translation_unit_visitor.cc
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *

src/common/visitor/translation_unit_visitor.h

@@ -1,5 +1,5 @@
 /**
- * src/common/visitor/translation_unit_visitor.h
+ * @file src/common/visitor/translation_unit_visitor.h
  *
  * Copyright (c) 2021-2023 Bartek Kryza <bkryza@gmail.com>
  *
@@ -46,8 +46,8 @@ public:
     /**
      * @brief Constructor
      *
-     * @param sm Reference to @link clang::SourceManager instance
+     * @param sm Reference to @ref clang::SourceManager instance
-     * @param config Reference to @link clanguml::config::diagram configuration
+     * @param config Reference to @ref clanguml::config::diagram configuration
      *        instance
      */
     explicit translation_unit_visitor(
@@ -65,7 +65,7 @@ public:
 
     /**
      * @brief Get clang::SourceManager
-     * @return Reference to @link clang::SourceManager used by this translation
+     * @return Reference to @ref clang::SourceManager used by this translation
      *         unit visitor
      */
     clang::SourceManager &source_manager() const;
@@ -73,7 +73,7 @@ public:
     /**
      * @brief Set source location in diagram element
      *
-     * @param decl Reference to @link clang::Decl
+     * @param decl Reference to @ref clang::Decl
      * @param element Reference to element to be updated
      */
     void set_source_location(const clang::Decl &decl,
@@ -82,7 +82,7 @@ public:
     /**
      * @brief Set source location in diagram element
      *
-     * @param expr Reference to @link clang::Expr
+     * @param expr Reference to @ref clang::Expr
      * @param element Reference to element to be updated
      */
     void set_source_location(const clang::Expr &expr,
@@ -94,7 +94,7 @@ public:
     /**
      * @brief Set source location in diagram element
      *
-     * @param location Reference to @link clang::SourceLocation
+     * @param location Reference to @ref clang::SourceLocation
      * @param element Reference to element to be updated
      */
     void set_source_location(const clang::SourceLocation &location,
@@ -104,7 +104,7 @@ protected:
     /**
      * @brief Set source location in diagram element
      *
-     * @param decl Reference to @link clang::NamedDecl
+     * @param decl Reference to @ref clang::NamedDecl
      * @param element Reference to element to be updated
      */
     void process_comment(const clang::NamedDecl &decl,

uml/class/comment_visitor_hierarchy_class.yml

@@ -0,0 +1,13 @@
+type: class
+include_relations_also_as_members: true
+glob:
+  - src/common/visitor/comment/*.cc
+include:
+  namespaces:
+    - clanguml::common::visitor::comment
+  subclasses:
+    - clanguml::common::visitor::comment::comment_visitor
+exclude:
+  access: [private, protected, public]
+using_namespace:
+  - clanguml

uml/class/relationship_context_class.yml

@@ -0,0 +1,18 @@
+type: class
+include_relations_also_as_members: true
+generate_packages: true
+glob:
+  - src/common/model/relationship.cc
+  - src/common/model/diagram_element.cc
+include:
+  namespaces:
+    - clanguml
+  context:
+    - clanguml::common::model::relationship
+exclude:
+  elements:
+    - clanguml::common::model::path
+  relationships:
+    - dependency
+using_namespace:
+  - clanguml

uml/class/source_file_hierarchy_class.yml

@@ -0,0 +1,13 @@
+type: class
+include_relations_also_as_members: true
+glob:
+  - src/common/model/source_file.cc
+include:
+  namespaces:
+    - clanguml
+  parents:
+    - clanguml::common::model::source_file
+exclude:
+  access: [private, protected, public]
+using_namespace:
+  - clanguml

uml/class/source_location_hierarchy_class.yml

@@ -0,0 +1,20 @@
+type: class
+include_relations_also_as_members: true
+generate_packages: true
+glob:
+  - src/common/model/*.cc
+  - src/class_diagram/model/*.cc
+  - src/sequence_diagram/model/*.cc
+  - src/include_diagram/model/*.cc
+  - src/package_diagram/model/*.cc
+include:
+  namespaces:
+    - clanguml
+  subclasses:
+    - clanguml::common::model::source_location
+  relationships:
+    - inheritance
+exclude:
+  access: [ public, protected, private ]
+using_namespace:
+  - clanguml

uml/class/stylable_element_hierarchy_class.yml

@@ -0,0 +1,20 @@
+type: class
+include_relations_also_as_members: true
+generate_packages: true
+glob:
+  - src/common/model/*.cc
+  - src/class_diagram/model/*.cc
+  - src/sequence_diagram/model/*.cc
+  - src/include_diagram/model/*.cc
+  - src/package_diagram/model/*.cc
+include:
+  namespaces:
+    - clanguml
+  subclasses:
+    - clanguml::common::model::stylable_element
+  relationships:
+    - inheritance
+exclude:
+  access: [public, protected, private]
+using_namespace:
+  - clanguml

uml/class/template_trait_hierarchy_class.yml

@@ -0,0 +1,21 @@
+type: class
+include_relations_also_as_members: true
+generate_packages: true
+glob:
+  - src/common/model/*.cc
+  - src/class_diagram/model/*.cc
+  - src/sequence_diagram/model/*.cc
+  - src/include_diagram/model/*.cc
+  - src/package_diagram/model/*.cc
+include:
+  namespaces:
+    - clanguml
+  subclasses:
+    - clanguml::common::model::template_trait
+  context:
+    - clanguml::common::model::template_trait
+exclude:
+  access: [ public, protected, private ]
+  relationships: [ dependency ]
+using_namespace:
+  - clanguml