Added doxygen comments to common namespace

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 config Reference to @link clanguml::config::diagram configuration
+     * @param sm Reference to @ref clang::SourceManager instance
+     * @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,