Fix diagram generation using LLVM 17 (Fixes #190)

Added 'title' diagram property

.clang-uml

@@ -1,6 +1,8 @@
 compilation_database_dir: debug
 output_directory: docs/diagrams
 comment_parser: clang
+remove_compile_flags:
+  - -Wno-class-memaccess
 generate_links:
   link: "{% if existsIn(element, \"doxygen_link\") %}{{ element.doxygen_link }}{% endif %}"
   tooltip: "{% if existsIn(element, \"comment\") and existsIn(element.comment, \"brief\") %}{{ abbrv(trim(replace(element.comment.brief.0, \"\\n+\", \" \")), 256) }}{% else %}{{ element.name }}{% endif %}"
@@ -72,4 +74,4 @@ diagrams:
     include!: uml/package/architecture_package.yml
   # Include diagrams
   include_graph:
-    include!: uml/include/include.yml
+    include!: uml/include/include.yml

CHANGELOG.md

@@ -1,5 +1,10 @@
 # CHANGELOG
 
+ * Excluded package diagram relationships to rejected packages (#185)
+ * Added 'title' diagram property (#184)
+ * Make sure sequence diagram messages generated during static variable
+   initialization are rendered only once (#183)
+
 ### 0.4.0
  * Added MermaidJS diagram generators (#27)
 

CMakeLists.txt

@@ -132,6 +132,20 @@ if(APPLE OR (LLVM_VERSION_MAJOR GREATER_EQUAL 16))
             ${CMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES})
 endif()
 
+#
+# Setup custom compile options depending on various compiler
+# and environment quirks
+#
+if(LLVM_VERSION_MAJOR GREATER_EQUAL 17)
+    if (CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
+        set(CUSTOM_COMPILE_OPTIONS "-Wno-class-memaccess")
+    endif()
+endif()
+if (CMAKE_CXX_COMPILER_ID STREQUAL "Clang")
+    set(CUSTOM_COMPILE_OPTIONS
+            "${CUSTOM_COMPILE_OPTIONS} -Wno-unused-private-field")
+endif()
+
 #
 # Setup threads library
 #

README.md

@@ -5,7 +5,7 @@
 [![Build status](https://github.com/bkryza/clang-uml/actions/workflows/build.yml/badge.svg)](https://github.com/bkryza/clang-uml/actions)
 [![Coverage](https://codecov.io/gh/bkryza/clang-uml/branch/master/graph/badge.svg)](https://codecov.io/gh/bkryza/clang-uml)
 [![Version](https://img.shields.io/badge/version-0.4.0-blue)](https://github.com/bkryza/clang-uml/releases)
-[![Version](https://img.shields.io/badge/LLVM-12,13,14,15,16-orange)](https://github.com/bkryza/clang-uml/releases)
+[![Version](https://img.shields.io/badge/LLVM-12,13,14,15,16,17-orange)](https://github.com/bkryza/clang-uml/releases)
 [![Doxygen](https://img.shields.io/badge/Docs-Doxygen-gainsboro)](https://clang-uml.github.io)
 
 `clang-uml` is an automatic C++ to UML class, sequence, package and include diagram generator, driven by
@@ -80,6 +80,7 @@ Nowadays, this file can be generated rather easily using multiple methods:
 * For Boost-based projects
   try [commands_to_compilation_database](https://github.com/tee3/commands_to_compilation_database)
 * For SCons, invoke `compilation_db` tool (requires SCons > 4.0.0)
+* For Bazel, try [bazel-compile-commands-extractor](https://github.com/hedronvision/bazel-compile-commands-extractor)
 * For Microsoft Visual Studio projects try [Clang Power Tools](https://www.clangpowertools.com)
 
 ### Invocation

docs/common_options.md

@@ -43,6 +43,17 @@ Effective configuration, including default values can be printed out in YAML for
 clang-uml --dump-config
 ```
 
+## Diagram titles
+Each type of diagram can have a `title` property, which will be generated in the
+diagram using directives specific to a given diagram generator, for instance:
+
+```yaml
+diagrams:
+  diagram1:
+    type: class
+    title: Some explanatory diagram title
+```
+
 ## Translation unit glob patterns
 One of the key options of the diagram configuration is the list of translation units, which should be parsed to
 get all necessary information for a diagram. 

src/CMakeLists.txt

@@ -25,8 +25,8 @@ endif(MSVC)
 target_compile_features(clang-umllib INTERFACE cxx_std_17)
 target_compile_options(clang-umllib PRIVATE
         $<$<OR:$<CXX_COMPILER_ID:Clang>,$<CXX_COMPILER_ID:GNU>>:
-        -Werror -Wall -Wextra -Wno-unused-parameter -Wno-unused-private-field
+        -Werror -Wall -Wextra -Wno-unused-parameter
-        -Wno-deprecated-declarations>
+        -Wno-deprecated-declarations ${CUSTOM_COMPILE_OPTIONS}>
         $<$<CXX_COMPILER_ID:MSVC>:/MP /W1 /bigobj /wd4291 /wd4624 /wd4244>)
 target_compile_definitions(clang-umllib PRIVATE
         $<$<CXX_COMPILER_ID:MSVC>:
@@ -40,8 +40,8 @@ add_executable(clang-uml ${MAIN_SOURCE_FILE})
 target_compile_features(clang-uml PUBLIC cxx_std_17)
 target_compile_options(clang-uml PRIVATE
         $<$<OR:$<CXX_COMPILER_ID:Clang>,$<CXX_COMPILER_ID:GNU>>:
-        -Werror -Wall -Wextra -Wno-unused-parameter -Wno-unused-private-field
+        -Werror -Wall -Wextra -Wno-unused-parameter
-        -Wno-deprecated-declarations>
+        -Wno-deprecated-declarations ${CUSTOM_COMPILE_OPTIONS}>
         $<$<CXX_COMPILER_ID:MSVC>:/MP /W1 /bigobj /wd4291 /wd4624 /wd4244>)
 target_compile_definitions(clang-uml PRIVATE
         ${ENABLE_BACKWARD_CPP})

src/common/generators/json/generator.h

@@ -110,6 +110,9 @@ void generator<C, D>::generate(std::ostream &ostr) const
     nlohmann::json j;
     j["name"] = generators::generator<C, D>::model().name();
     j["diagram_type"] = to_string(generators::generator<C, D>::model().type());
+    if (generators::generator<C, D>::config().title) {
+        j["title"] = generators::generator<C, D>::config().title();
+    }
 
     generate_diagram(j);
 

src/common/generators/mermaid/generator.h

@@ -136,6 +136,16 @@ public:
      */
     void generate_metadata(std::ostream &ostr) const;
 
+    /**
+     * @brief Generate diagram title
+     *
+     * Generates a MermaidJS diagram title directive if diagram title
+     * is provided in the diagram configuration.
+     *
+     * @param ostr Output stream
+     */
+    void generate_title(std::ostream &ostr) const;
+
     /**
      * @brief Generate hyper link to element
      *
@@ -238,6 +248,8 @@ void generator<C, D>::generate(std::ostream &ostr) const
 
     update_context();
 
+    generate_title(ostr);
+
     generate_diagram_type(ostr);
 
     generate_mermaid_directives(ostr, config.mermaid().before);
@@ -399,6 +411,18 @@ void generator<C, D>::generate_metadata(std::ostream &ostr) const
     }
 }
 
+template <typename C, typename D>
+void generator<C, D>::generate_title(std::ostream &ostr) const
+{
+    const auto &config = generators::generator<C, D>::config();
+
+    if (config.title) {
+        ostr << "---\n";
+        ostr << "title: " << config.title() << '\n';
+        ostr << "---\n";
+    }
+}
+
 template <typename C, typename D>
 void generator<C, D>::print_debug(
     const common::model::source_location &e, std::ostream &ostr) const

src/common/generators/plantuml/generator.h

@@ -131,6 +131,16 @@ public:
      */
     void generate_metadata(std::ostream &ostr) const;
 
+    /**
+     * @brief Generate diagram title
+     *
+     * Generates a PlantUML diagram title directive if diagram title
+     * is provided in the diagram configuration.
+     *
+     * @param ostr Output stream
+     */
+    void generate_title(std::ostream &ostr) const;
+
     /**
      * @brief Generate hyper link to element
      *
@@ -241,6 +251,8 @@ void generator<C, D>::generate(std::ostream &ostr) const
 
     ostr << "@startuml" << '\n';
 
+    generate_title(ostr);
+
     generate_plantuml_directives(ostr, config.puml().before);
 
     generate_diagram(ostr);
@@ -449,6 +461,16 @@ void generator<C, D>::generate_metadata(std::ostream &ostr) const
     }
 }
 
+template <typename C, typename D>
+void generator<C, D>::generate_title(std::ostream &ostr) const
+{
+    const auto &config = generators::generator<C, D>::config();
+
+    if (config.title) {
+        ostr << "title " << config.title() << '\n';
+    }
+}
+
 template <typename C, typename D>
 template <typename E>
 void generator<C, D>::generate_link(std::ostream &ostr, const E &e) const

src/common/model/diagram_element.cc

@@ -30,6 +30,16 @@ diagram_element::id_t diagram_element::id() const { return id_; }
 
 void diagram_element::set_id(diagram_element::id_t id) { id_ = id; }
 
+std::optional<id_t> diagram_element::parent_element_id() const
+{
+    return parent_element_id_;
+}
+
+void diagram_element::set_parent_element_id(diagram_element::id_t id)
+{
+    parent_element_id_ = id;
+}
+
 std::string diagram_element::alias() const
 {
     assert(id_ >= 0);

src/common/model/diagram_element.h

@@ -64,6 +64,20 @@ public:
      */
     void set_id(id_t id);
 
+    /**
+     * Get elements parent package id.
+     *
+     * @return Parent package id if element is nested.
+     */
+    std::optional<id_t> parent_element_id() const;
+
+    /**
+     * Set elements parent package id.
+     *
+     * @param id Id of parent package.
+     */
+    void set_parent_element_id(diagram_element::id_t id);
+
     /**
      * @brief Return elements' diagram alias.
      *
@@ -174,6 +188,7 @@ public:
 
 private:
     id_t id_{0};
+    std::optional<id_t> parent_element_id_{0};
     std::string name_;
     std::vector<relationship> relationships_;
     bool nested_{false};

src/common/model/diagram_filter.cc

@@ -248,10 +248,6 @@ tvl::value_t namespace_filter::match(const diagram &d, const element &e) const
                     e.full_name(false);
             });
 
-        if (tvl::is_false(result))
-            LOG_DBG("Element {} rejected by namespace_filter 1",
-                e.full_name(false));
-
         return result;
     }
 
@@ -273,10 +269,6 @@ tvl::value_t namespace_filter::match(const diagram &d, const element &e) const
                     e.full_name(false);
             });
 
-        if (tvl::is_false(result))
-            LOG_DBG("Element {} rejected by namespace_filter (package diagram)",
-                e.full_name(false));
-
         return result;
     }
 
@@ -290,9 +282,6 @@ tvl::value_t namespace_filter::match(const diagram &d, const element &e) const
             return std::get<common::regex>(nsit.value()) %= e.full_name(false);
         });
 
-    if (tvl::is_false(result))
-        LOG_DBG("Element {} rejected by namespace_filter", e.full_name(false));
-
     return result;
 }
 

src/common/model/nested_trait.h

@@ -94,9 +94,11 @@ public:
 
         auto parent = get_element(path);
 
-        if (parent && dynamic_cast<nested_trait<T, Path> *>(&parent.value()))
+        if (parent && dynamic_cast<nested_trait<T, Path> *>(&parent.value())) {
+            p->set_parent_element_id(parent.value().id());
             return dynamic_cast<nested_trait<T, Path> &>(parent.value())
                 .template add_element<V>(std::move(p));
+        }
 
         LOG_INFO("No parent element found at: {}", path.to_string());
 

src/common/model/template_parameter.h

@@ -504,8 +504,6 @@ private:
     /*! Whether template argument is ellipsis (...) */
     bool is_ellipsis_{false};
 
-    bool is_noexcept_{false};
-
     /*! Whether the template parameter is variadic */
     bool is_variadic_{false};
 

src/common/visitor/translation_unit_visitor.cc

@@ -123,6 +123,12 @@ void translation_unit_visitor::set_source_location(
         }
     }
 
+    if (std::filesystem::path file_path{file}; !file_path.is_absolute()) {
+        file_path =
+            std::filesystem::canonical(std::filesystem::absolute(file_path));
+        file = file_path.string();
+    }
+
     element.set_file(file);
     element.set_file_relative(util::path_to_url(
         std::filesystem::relative(element.file(), relative_to_path_).string()));

src/config/config.h

@@ -537,6 +537,8 @@ struct diagram : public inheritable_diagram_options {
     void initialize_type_aliases();
 
     std::string name;
+
+    option<std::string> title{"title"};
 };
 
 /**

src/config/schema.h

@@ -156,6 +156,7 @@ types:
         relative_to: !optional string
         using_namespace: !optional [string, [string]]
         generate_metadata: !optional bool
+        title: !optional string
         #
         # Class diagram specific options
         #
@@ -192,6 +193,7 @@ types:
         relative_to: !optional string
         using_namespace: !optional [string, [string]]
         generate_metadata: !optional bool
+        title: !optional string
         #
         # Sequence diagram specific options
         #
@@ -226,6 +228,7 @@ types:
         relative_to: !optional string
         using_namespace: !optional [string, [string]]
         generate_metadata: !optional bool
+        title: !optional string
         #
         # Package diagram specific options
         #
@@ -254,6 +257,7 @@ types:
         relative_to: !optional string
         using_namespace: !optional [string, [string]]
         generate_metadata: !optional bool
+        title: !optional string
         #
         # Include diagram specific options
         #

src/config/yaml_decoders.cc

@@ -551,6 +551,7 @@ template <typename T> bool decode_diagram(const Node &node, T &rhs)
     get_option(node, rhs.comment_parser);
     get_option(node, rhs.debug_mode);
     get_option(node, rhs.generate_metadata);
+    get_option(node, rhs.title);
 
     return true;
 }

src/config/yaml_emitters.cc

@@ -297,7 +297,9 @@ YAML::Emitter &operator<<(
     out << c.using_namespace;
     out << c.generate_metadata;
 
-    if (dynamic_cast<const class_diagram *>(&c) != nullptr) {
+    if (const auto *cd = dynamic_cast<const class_diagram *>(&c);
+        cd != nullptr) {
+        out << cd->title;
         out << c.generate_method_arguments;
         out << c.generate_packages;
         out << c.include_relations_also_as_members;
@@ -315,18 +317,24 @@ YAML::Emitter &operator<<(
         out << c.generate_template_argument_dependencies;
         out << c.skip_redundant_dependencies;
     }
-    else if (dynamic_cast<const sequence_diagram *>(&c) != nullptr) {
+    else if (const auto *sd = dynamic_cast<const sequence_diagram *>(&c);
+             sd != nullptr) {
+        out << sd->title;
         out << c.combine_free_functions_into_file_participants;
         out << c.generate_condition_statements;
         out << c.generate_method_arguments;
         out << c.generate_return_types;
         out << c.participants_order;
     }
-    else if (dynamic_cast<const package_diagram *>(&c) != nullptr) {
+    else if (const auto *pd = dynamic_cast<const package_diagram *>(&c);
+             pd != nullptr) {
+        out << pd->title;
         out << c.generate_packages;
         out << c.package_type;
     }
-    else if (dynamic_cast<const include_diagram *>(&c) != nullptr) {
+    else if (const auto *id = dynamic_cast<const include_diagram *>(&c);
+             id != nullptr) {
+        out << id->title;
         out << c.generate_system_headers;
     }
 

src/package_diagram/generators/json/package_diagram_generator.cc

@@ -36,6 +36,14 @@ void generator::generate_relationships(
     if (model().should_include(relationship_t::kDependency)) {
         for (const auto &r : p.relationships()) {
             nlohmann::json rel = r;
+
+            auto destination_package = model().get(r.destination());
+
+            if (!destination_package ||
+                !model().should_include(
+                    dynamic_cast<const package &>(*destination_package)))
+                continue;
+
             rel["source"] = std::to_string(p.id());
             parent["relationships"].push_back(std::move(rel));
         }

src/package_diagram/generators/mermaid/package_diagram_generator.cc

@@ -45,9 +45,17 @@ void generator::generate_relationships(
         for (const auto &r : p.relationships()) {
             std::stringstream relstr;
             try {
-                auto destination = model().to_alias(r.destination());
+                auto destination_package = model().get(r.destination());
-                if (!destination.empty()) {
+
-                    relstr << p.alias() << " -.-> " << destination << '\n';
+                if (!destination_package ||
+                    !model().should_include(
+                        dynamic_cast<const package &>(*destination_package)))
+                    continue;
+
+                auto destination_alias = model().to_alias(r.destination());
+                if (!destination_alias.empty()) {
+                    relstr << p.alias() << " -.-> " << destination_alias
+                           << '\n';
                     ostr << indent(1) << relstr.str();
                 }
             }

src/package_diagram/generators/plantuml/package_diagram_generator.cc

@@ -38,9 +38,17 @@ void generator::generate_relationships(
         for (const auto &r : p.relationships()) {
             std::stringstream relstr;
             try {
-                auto destination = model().to_alias(r.destination());
+                auto destination_package = model().get(r.destination());
-                if (!destination.empty()) {
+
-                    relstr << p.alias() << " ..> " << destination << '\n';
+                if (!destination_package ||
+                    !model().should_include(
+                        dynamic_cast<const package &>(*destination_package)))
+                    continue;
+
+                auto destination_alias = model().to_alias(r.destination());
+
+                if (!destination_alias.empty()) {
+                    relstr << p.alias() << " ..> " << destination_alias << '\n';
                     ostr << relstr.str();
                 }
             }
@@ -54,8 +62,9 @@ void generator::generate_relationships(
 
     // Process it's subpackages relationships
     for (const auto &subpackage : p) {
-        generate_relationships(
+        if (model().should_include(dynamic_cast<const package &>(*subpackage)))
-            dynamic_cast<const package &>(*subpackage), ostr);
+            generate_relationships(
+                dynamic_cast<const package &>(*subpackage), ostr);
     }
 }
 

src/package_diagram/visitor/translation_unit_visitor.cc

@@ -76,12 +76,12 @@ bool translation_unit_visitor::VisitNamespaceDecl(clang::NamespaceDecl *ns)
     p->set_name(name);
     p->set_namespace(package_parent);
     p->set_id(common::to_id(*ns));
+    set_source_location(*ns, *p);
 
     assert(p->id() > 0);
 
     if (diagram().should_include(*p) && !diagram().get(p->id())) {
         process_comment(*ns, *p);
-        set_source_location(*ns, *p);
 
         p->set_style(p->style_spec());
 
@@ -232,8 +232,10 @@ void translation_unit_visitor::add_relationships(
 
         pkg->set_name(pkg_name);
         pkg->set_id(get_package_id(cls));
+        set_source_location(*cls, *pkg);
 
-        diagram().add(parent_path, std::move(pkg));
+        if (diagram().should_include(*pkg))
+            diagram().add(parent_path, std::move(pkg));
     }
 
     auto current_package_id = get_package_id(cls);
@@ -246,8 +248,21 @@ void translation_unit_visitor::add_relationships(
     auto current_package = diagram().get(current_package_id);
 
     if (current_package) {
+        std::vector<common::model::diagram_element::id_t> parent_ids =
+            get_parent_package_ids(current_package_id);
+
         for (const auto &dependency : relationships) {
             const auto destination_id = std::get<0>(dependency);
+
+            // Skip dependency relationships to parent packages
+            if (util::contains(parent_ids, destination_id))
+                continue;
+
+            // Skip dependency relationship to child packages
+            if (util::contains(
+                    get_parent_package_ids(destination_id), current_package_id))
+                continue;
+
             relationship r{relationship_t::kDependency, destination_id,
                 common::model::access_t::kNone};
             if (destination_id != current_package_id)
@@ -605,4 +620,23 @@ translation_unit_visitor::config() const
 
 void translation_unit_visitor::finalize() { }
 
+std::vector<common::model::diagram_element::id_t>
+translation_unit_visitor::get_parent_package_ids(
+    common::model::diagram_element::id_t id)
+{
+    std::vector<common::model::diagram_element::id_t> parent_ids;
+    std::optional<common::model::diagram_element::id_t> parent_id = id;
+
+    while (parent_id.has_value()) {
+        parent_ids.push_back(parent_id.value());
+        auto parent = this->diagram().get(parent_id.value());
+        if (parent)
+            parent_id = parent.value().parent_element_id();
+        else
+            break;
+    }
+
+    return parent_ids;
+}
+
 } // namespace clanguml::package_diagram::visitor

src/package_diagram/visitor/translation_unit_visitor.h

@@ -214,6 +214,9 @@ private:
     void add_relationships(
         clang::Decl *cls, found_relationships_t &relationships);
 
+    std::vector<common::model::diagram_element::id_t> get_parent_package_ids(
+        common::model::diagram_element::id_t id);
+
     // Reference to the output diagram model
     clanguml::package_diagram::model::diagram &diagram_;
 

src/sequence_diagram/model/diagram.h

@@ -328,8 +328,6 @@ private:
         return block_end_types.count(mt) > 0;
     };
 
-    bool started_{false};
-
     std::map<common::model::diagram_element::id_t, activity> sequences_;
 
     std::map<common::model::diagram_element::id_t, std::unique_ptr<participant>>

src/sequence_diagram/visitor/translation_unit_visitor.cc

@@ -1039,10 +1039,6 @@ bool translation_unit_visitor::TraverseVarDecl(clang::VarDecl *decl)
         decl->getBeginLoc().printToString(source_manager()),
         context().caller_id());
 
-    decl->dump();
-
-    decl->getInit()->dump();
-
     if (decl->isStaticLocal())
         within_static_variable_declaration_++;
 
@@ -1074,8 +1070,6 @@ bool translation_unit_visitor::VisitCXXConstructExpr(
         expr->getBeginLoc().printToString(source_manager()),
         context().caller_id());
 
-    expr->dump();
-
     message m{message_t::kCall, context().caller_id()};
 
     m.in_static_declaration_context(within_static_variable_declaration_ > 0);

tests/CMakeLists.txt

@@ -58,8 +58,9 @@ foreach(TEST_NAME ${TEST_CASES})
     target_compile_options(${TEST_NAME} PRIVATE
             $<$<COMPILE_LANGUAGE:CXX>:
             $<$<OR:$<CXX_COMPILER_ID:Clang>,$<CXX_COMPILER_ID:GNU>>:
-            -Wno-unused-parameter -Wno-unused-private-field -Wno-unused-variable
+            -Wno-unused-parameter -Wno-unused-variable
-            -Wno-attributes -Wno-nonnull -Wno-deprecated-enum-enum-conversion>
+            -Wno-attributes -Wno-nonnull -Wno-deprecated-enum-enum-conversion
+            ${CUSTOM_COMPILE_OPTIONS}>
             $<$<CXX_COMPILER_ID:MSVC>:/W1 /bigobj /wd4624>>)
     target_link_libraries(${TEST_NAME} PRIVATE ${CLANG_UML_TEST_LIBRARIES})
 endforeach()

tests/catch.h

@@ -13301,9 +13301,6 @@ bool RegexMatcher::match(std::string const &matchee) const
 {
     auto flags = std::regex::ECMAScript; // ECMAScript is the default syntax
                                          // option anyway
-#if !defined(_WIN32)
-    flags |= std::regex::multiline;
-#endif
 
     if (m_caseSensitivity == CaseSensitive::Choice::No) {
         flags |= std::regex::icase;

tests/t00002/.clang-uml

@@ -3,6 +3,7 @@ output_directory: diagrams
 diagrams:
   t00002_class:
     type: class
+    title: Basic class diagram example
     glob:
       - ../../tests/t00002/t00002.cc
     comment_parser: clang

tests/t00002/test_case.h

@@ -41,6 +41,7 @@ TEST_CASE("t00002", "[test-case][class]")
 
         REQUIRE_THAT(puml, StartsWith("@startuml"));
         REQUIRE_THAT(puml, EndsWith("@enduml\n"));
+        REQUIRE_THAT(puml, HasTitle("Basic class diagram example"));
         REQUIRE_THAT(puml, IsAbstractClass(_A("A")));
         REQUIRE_THAT(puml, IsClass(_A("B")));
         REQUIRE_THAT(puml, IsClass(_A("C")));
@@ -92,6 +93,7 @@ TEST_CASE("t00002", "[test-case][class]")
 
         using namespace json;
 
+        REQUIRE(HasTitle(j, "Basic class diagram example"));
         REQUIRE(IsClass(j, "A"));
         REQUIRE(IsClass(j, "B"));
         REQUIRE(IsClass(j, "C"));
@@ -111,9 +113,11 @@ TEST_CASE("t00002", "[test-case][class]")
 
         mermaid::AliasMatcher _A(mmd);
         using mermaid::HasNote;
+        using mermaid::HasTitle;
         using mermaid::IsAbstractClass;
 
-        REQUIRE_THAT(mmd, StartsWith("classDiagram"));
+        REQUIRE_THAT(mmd, HasTitle("Basic class diagram example"));
+        REQUIRE_THAT(mmd, Contains("classDiagram"));
         REQUIRE_THAT(mmd, IsAbstractClass(_A("A")));
         REQUIRE_THAT(mmd, IsClass(_A("B")));
         REQUIRE_THAT(mmd, IsClass(_A("C")));

tests/t20001/.clang-uml

@@ -3,6 +3,7 @@ output_directory: diagrams
 diagrams:
   t20001_sequence:
     type: sequence
+    title: Basic sequence diagram example
     glob:
       - ../../tests/t20001/t20001.cc
     include:

tests/t20001/test_case.h

@@ -35,6 +35,8 @@ TEST_CASE("t20001", "[test-case][sequence]")
         REQUIRE_THAT(src, StartsWith("@startuml"));
         REQUIRE_THAT(src, EndsWith("@enduml\n"));
 
+        REQUIRE_THAT(src, HasTitle("Basic sequence diagram example"));
+
         REQUIRE_THAT(src, HasCall(_A("B"), _A("A"), "add3(int,int,int)"));
         REQUIRE_THAT(src, HasCall(_A("A"), "add(int,int)"));
         REQUIRE_THAT(src, !HasCall(_A("A"), _A("detail::C"), "add(int,int)"));
@@ -50,6 +52,8 @@ TEST_CASE("t20001", "[test-case][sequence]")
 
         using namespace json;
 
+        REQUIRE(HasTitle(j, "Basic sequence diagram example"));
+
         REQUIRE(IsFunctionParticipant(j, "tmain()"));
         REQUIRE(IsClassParticipant(j, "A"));
         REQUIRE(IsClassParticipant(j, "B"));
@@ -71,6 +75,9 @@ TEST_CASE("t20001", "[test-case][sequence]")
         mermaid::SequenceDiagramAliasMatcher _A(src);
         using mermaid::HasCall;
         using mermaid::HasComment;
+        using mermaid::HasTitle;
+
+        REQUIRE_THAT(src, HasTitle("Basic sequence diagram example"));
 
         REQUIRE_THAT(src, HasCall(_A("B"), _A("A"), "add3(int,int,int)"));
         REQUIRE_THAT(src, HasCall(_A("A"), "add(int,int)"));

tests/t30001/.clang-uml

@@ -3,6 +3,7 @@ output_directory: diagrams
 diagrams:
   t30001_package:
     type: package
+    title: Basic package diagram example
     glob:
       - ../../tests/t30001/t30001.cc
     include:

tests/t30001/test_case.h

@@ -35,6 +35,8 @@ TEST_CASE("t30001", "[test-case][package]")
         REQUIRE_THAT(src, StartsWith("@startuml"));
         REQUIRE_THAT(src, EndsWith("@enduml\n"));
 
+        REQUIRE_THAT(src, HasTitle("Basic package diagram example"));
+
         REQUIRE_THAT(src, IsPackage("A"));
         REQUIRE_THAT(src, IsPackage("AAA"));
         REQUIRE_THAT(src, IsPackage("AAA"));
@@ -69,6 +71,8 @@ TEST_CASE("t30001", "[test-case][package]")
 
         using namespace json;
 
+        REQUIRE(HasTitle(j, "Basic package diagram example"));
+
         REQUIRE(IsPackage(j, "A"));
         REQUIRE(IsPackage(j, "A::AA"));
         REQUIRE(IsPackage(j, "A::AA::AAA"));
@@ -90,8 +94,11 @@ TEST_CASE("t30001", "[test-case][package]")
         using mermaid::HasComment;
         using mermaid::HasLink;
         using mermaid::HasPackageNote;
+        using mermaid::HasTitle;
         using mermaid::IsPackage;
 
+        REQUIRE_THAT(src, HasTitle("Basic package diagram example"));
+
         REQUIRE_THAT(src, IsPackage(_A("A")));
         REQUIRE_THAT(src, IsPackage(_A("AAA")));
         REQUIRE_THAT(src, IsPackage(_A("AAA")));

tests/t40001/.clang-uml

@@ -3,6 +3,7 @@ output_directory: diagrams
 diagrams:
   t40001_include:
     type: include
+    title: Basic include diagram example
     # Provide the files to parse in order to look
     # for #include directives
     glob:

tests/t40001/test_case.h

@@ -35,6 +35,7 @@ TEST_CASE("t40001", "[test-case][include]")
 
         REQUIRE_THAT(src, StartsWith("@startuml"));
         REQUIRE_THAT(src, EndsWith("@enduml\n"));
+        REQUIRE_THAT(src, HasTitle("Basic include diagram example"));
 
         REQUIRE_THAT(src, IsFolder("lib1"));
         REQUIRE_THAT(src, IsFile("lib1.h"));
@@ -60,6 +61,8 @@ TEST_CASE("t40001", "[test-case][include]")
 
         using namespace json;
 
+        REQUIRE(HasTitle(j, "Basic include diagram example"));
+
         REQUIRE(IsFolder(j, "include"));
         REQUIRE(IsFolder(j, "include/lib1"));
         REQUIRE(IsFolder(j, "src"));
@@ -84,10 +87,13 @@ TEST_CASE("t40001", "[test-case][include]")
 
         mermaid::AliasMatcher _A(src);
         using mermaid::HasComment;
+        using mermaid::HasTitle;
         using mermaid::IsFile;
         using mermaid::IsFolder;
         using mermaid::IsIncludeDependency;
 
+        REQUIRE_THAT(src, HasTitle("Basic include diagram example"));
+
         REQUIRE_THAT(src, IsFolder(_A("lib1")));
         REQUIRE_THAT(src, IsFile(_A("lib1.h")));
         REQUIRE_THAT(src, IsFile(_A("t40001.cc")));

tests/test_cases.cc

@@ -263,12 +263,12 @@ template <typename T>
 void save_diagram(const std::filesystem::path &path, const T &diagram)
 {
     static_assert(
-        std::same_as<T, std::string> || std::same_as<T, nlohmann::json>);
+        std::is_same_v<T, std::string> || std::is_same_v<T, nlohmann::json>);
 
     std::filesystem::create_directories(path.parent_path());
     std::ofstream ofs;
     ofs.open(path, std::ofstream::out | std::ofstream::trunc);
-    if constexpr (std::same_as<T, nlohmann::json>) {
+    if constexpr (std::is_same_v<T, nlohmann::json>) {
         ofs << std::setw(2) << diagram;
     }
     else {

tests/test_cases.h

@@ -494,6 +494,20 @@ struct SequenceDiagramAliasMatcher {
 };
 }
 
+ContainsMatcher HasTitle(std::string const &str,
+    CaseSensitive::Choice caseSensitivity = CaseSensitive::Yes)
+{
+    return ContainsMatcher(CasedString("title " + str, caseSensitivity));
+}
+
+namespace mermaid {
+ContainsMatcher HasTitle(std::string const &str,
+    CaseSensitive::Choice caseSensitivity = CaseSensitive::Yes)
+{
+    return ContainsMatcher(CasedString("title: " + str, caseSensitivity));
+}
+}
+
 ContainsMatcher IsClass(std::string const &str,
     CaseSensitive::Choice caseSensitivity = CaseSensitive::Yes)
 {
@@ -1231,6 +1245,11 @@ std::string expand_name(const nlohmann::json &j, const std::string &name)
     return fmt::format("{}::{}", j["using_namespace"].get<std::string>(), name);
 }
 
+bool HasTitle(const nlohmann::json &j, const std::string &title)
+{
+    return j.contains("title") && j["title"] == title;
+}
+
 bool IsClass(const nlohmann::json &j, const std::string &name)
 {
     auto e = get_element(j, expand_name(j, name));

uml/class/architecture_visitors_class.yml

@@ -1,4 +1,5 @@
 type: class
+title: Translation unit AST visitors
 generate_packages: true
 glob:
   - src/docs/architecture.cc

uml/class/class_model_class.yml

@@ -1,4 +1,5 @@
 type: class
+title: Class diagram model
 include_relations_also_as_members: false
 generate_method_arguments: none
 generate_packages: true
@@ -13,7 +14,4 @@ exclude:
   relationships:
     - dependency
 using_namespace:
-  - clanguml
+  - clanguml
-plantuml:
-  before:
-    - 'title clang-uml class diagram model'

uml/class/comment_visitor_hierarchy_class.yml

@@ -1,4 +1,5 @@
 type: class
+title: Comment visitor class hierarchy
 include_relations_also_as_members: true
 glob:
   - src/common/visitor/comment/*.cc

uml/class/common_model_class.yml

@@ -1,4 +1,5 @@
 type: class
+title: Common diagram model
 include_relations_also_as_members: false
 glob:
   - src/common/model/*.cc
@@ -16,7 +17,5 @@ exclude:
 using_namespace:
   - clanguml::common::model
 plantuml:
-  before:
-    - 'title clang-uml common diagram model'
   after:
     - 'note top of {{ alias("diagram") }}: Common class for specific diagram types'

uml/class/compilation_database_context_class.yml

@@ -1,4 +1,5 @@
 type: class
+title: Compilation database context diagram
 include_relations_also_as_members: true
 generate_packages: false
 glob:

uml/class/config_class.yml

@@ -1,4 +1,5 @@
 type: class
+title: Configuration model
 include_relations_also_as_members: true
 glob:
   - src/config/config.cc
@@ -15,8 +16,6 @@ exclude:
 using_namespace:
   - clanguml::config
 plantuml:
-  before:
-    - 'title clang-uml configuration model'
   after:
     - 'note left of {{ alias("inheritable_diagram_options") }}: Options common to all diagram types.'
     - 'note right of {{ alias("config") }}: General options not used by diagrams.'

uml/class/config_context_class.yml

@@ -1,4 +1,5 @@
 type: class
+title: clanguml::config::config context diagram
 include_relations_also_as_members: true
 glob:
   - src/config/config.cc
@@ -8,7 +9,4 @@ include:
   context:
     - clanguml::config::config
 using_namespace:
-  - clanguml::config
+  - clanguml::config
-plantuml:
-  before:
-    - 'title clanguml::config::config context diagram'

uml/class/decorated_element_hierarchy_class.yml

@@ -1,4 +1,5 @@
 type: class
+title: Decorated diagram element class hierarchy
 include_relations_also_as_members: true
 generate_packages: true
 glob:

uml/class/decorators_class.yml

@@ -1,4 +1,5 @@
 type: class
+title: Diagram element decorators model
 include_relations_also_as_members: false
 glob:
   - src/decorators/decorators.cc
@@ -6,7 +7,4 @@ include:
   namespaces:
     - clanguml::decorators
 using_namespace:
-  - clanguml::decorators
+  - clanguml::decorators
-plantuml:
-  before:
-    - 'title clang-uml decorators model'

uml/class/diagram_config_hierarchy_class.yml

@@ -1,4 +1,5 @@
 type: class
+title: Configuration model class hierarchy
 include_relations_also_as_members: true
 generate_packages: true
 glob:
@@ -13,7 +14,4 @@ include:
 exclude:
   access: [public, protected, private]
 using_namespace:
-  - clanguml
+  - clanguml
-plantuml:
-  before:
-    - 'title clanguml::config::diagram class hierarchy'

uml/class/diagram_element_hierarchy_class.yml

@@ -1,4 +1,5 @@
 type: class
+title: Diagram element class hierarchy
 generate_packages: true
 glob:
   - src/common/model/*.cc
@@ -22,7 +23,4 @@ exclude:
     - private
     - protected
 using_namespace:
-  - clanguml
+  - clanguml
-plantuml:
-  before:
-    - 'title clang-uml diagram element class inheritance model'

uml/class/diagram_filter_context_class.yml

@@ -1,4 +1,5 @@
 type: class
+title: Diagram filter context model
 include_relations_also_as_members: true
 generate_packages: false
 glob:

uml/class/diagram_hierarchy_class.yml

@@ -1,4 +1,5 @@
 type: class
+title: Diagram type class hierarchy
 include_relations_also_as_members: true
 generate_packages: true
 generate_method_arguments: none

uml/class/diagram_model_class.yml

@@ -1,4 +1,5 @@
 type: class
+title: Diagram model
 include_relations_also_as_members: false
 generate_method_arguments: none
 glob:
@@ -16,7 +17,4 @@ exclude:
   relationships:
     - dependency
 using_namespace:
-  - clanguml
+  - clanguml
-plantuml:
-  before:
-    - 'title clang-uml diagram model'

uml/class/filter_visitor_hierarchy_class.yml

@@ -1,4 +1,5 @@
 type: class
+title: Diagram filter visitor class hierarchy
 include_relations_also_as_members: true
 generate_packages: true
 glob:

uml/class/inheritable_diagram_options_context_class.yml

@@ -1,4 +1,5 @@
 type: class
+title: Configuration model inheritable options context
 include_relations_also_as_members: true
 glob:
   - src/config/config.cc
@@ -11,5 +12,4 @@ using_namespace:
   - clanguml::config
 plantuml:
   before:
-    - title clanguml::config::config context diagram
     - left to right direction

uml/class/nested_trait_hierarchy_class.yml

@@ -1,4 +1,5 @@
 type: class
+title: Nested trait model class hierarchy
 include_relations_also_as_members: true
 glob:
   - src/common/model/*.cc

uml/class/package_hierarchy_class.yml

@@ -1,4 +1,5 @@
 type: class
+title: Package diagram class hierarchy
 include_relations_also_as_members: true
 glob:
   - src/common/model/package.cc

uml/class/package_model_class.yml

@@ -1,4 +1,5 @@
 type: class
+title: Package diagram model
 include_relations_also_as_members: false
 generate_method_arguments: none
 glob:
@@ -12,7 +13,4 @@ using_namespace:
   - clanguml::package_diagram::model
 exclude:
   relationships:
-    - dependency
+    - dependency
-plantuml:
-  before:
-    - 'title clang-uml package diagram model'

uml/class/relationship_context_class.yml

@@ -1,4 +1,5 @@
 type: class
+title: Relationship model context
 include_relations_also_as_members: true
 generate_packages: true
 glob:

uml/class/sequence_model_class.yml

@@ -1,4 +1,5 @@
 type: class
+title: Sequence diagram model
 include_relations_also_as_members: true
 generate_method_arguments: none
 generate_packages: true
@@ -23,7 +24,4 @@ exclude:
     - destructor
     - operator
 using_namespace:
-  - clanguml
+  - clanguml
-plantuml:
-  before:
-    - 'title clang-uml sequence diagram model'

uml/class/source_file_hierarchy_class.yml

@@ -1,4 +1,5 @@
 type: class
+title: Source file model class hierarchy
 include_relations_also_as_members: true
 glob:
   - src/common/model/source_file.cc

uml/class/source_location_hierarchy_class.yml

@@ -1,4 +1,5 @@
 type: class
+title: Source location model class hierarchy
 include_relations_also_as_members: true
 generate_packages: true
 glob:

uml/class/stylable_element_hierarchy_class.yml

@@ -1,4 +1,5 @@
 type: class
+title: Stylable diagram element class hierarchy
 include_relations_also_as_members: true
 generate_packages: true
 glob:

uml/class/template_trait_hierarchy_class.yml

@@ -1,4 +1,5 @@
 type: class
+title: Template trait diagram element model class hierarchy
 include_relations_also_as_members: true
 generate_packages: true
 glob:

uml/include/include.yml

@@ -1,10 +1,8 @@
 type: include
+title: Include graph
 glob:
   - src/config/*.cc
 relative_to: .
 include:
   paths:
-    - src
+    - src
-plantuml:
-  before:
-    - "title clang-uml include graph diagram"

uml/package/architecture_package.yml

@@ -1,4 +1,5 @@
 type: package
+title: High-level namespace dependencies in clang-uml
 glob:
   - src/config/config.cc
   - src/common/model/diagram.cc
@@ -15,7 +16,4 @@ include:
     - r: "clanguml::.+_diagram"
     - r: "clanguml::.+::model"
     - r: "clanguml::.+::visitor"
-    - r: "clanguml::.+::generators"
+    - r: "clanguml::.+::generators"
-plantuml:
-  before:
-    - 'title clang-uml top level packages'

uml/package/main_package.yml

@@ -1,11 +1,9 @@
 type: package
+title: Namespace (package) diagram
 glob:
   - src/**/*.cc
 include:
   namespaces:
     - clanguml
 using_namespace:
-  - clanguml
+  - clanguml
-plantuml:
-  before:
-    - 'title clang-uml namespaces'

uml/sequence/class_diagram_generator_sequence.yml

@@ -1,4 +1,5 @@
 type: sequence
+title: PlantUML diagram generator sequence diagram
 glob:
   - src/class_diagram/generators/plantuml/*.cc
 include:
@@ -6,8 +7,5 @@ include:
     - clanguml
 using_namespace:
   - clanguml::class_diagram::generators::plantuml
-plantuml:
-  before:
-    - 'title clang-uml clanguml::class_diagram::generators::plantuml::generator sequence diagram'
 from:
   - function: "clanguml::common::generators::plantuml::generator<clanguml::config::class_diagram,clanguml::class_diagram::model::diagram>::generate(std::ostream &) const"

uml/sequence/cli_handle_options_sequence.yml

@@ -1,4 +1,5 @@
 type: sequence
+title: CLI options handling sequence diagram
 combine_free_functions_into_file_participants: true
 generate_method_arguments: none
 debug_mode: true

uml/sequence/diagram_generate_generic_sequence.yml

@@ -1,4 +1,5 @@
 type: sequence
+title: Common sequence diagram generator sequence diagram
 combine_free_functions_into_file_participants: true
 generate_method_arguments: none
 glob:

uml/sequence/load_config_sequence.yml

@@ -1,4 +1,5 @@
 type: sequence
+title: Configuration file loading sequence diagram
 combine_free_functions_into_file_participants: true
 generate_method_arguments: none
 glob:

uml/sequence/main_sequence.yml

@@ -1,4 +1,5 @@
 type: sequence
+title: main() function sequence diagram
 # Group free functions into one participant per file
 combine_free_functions_into_file_participants: true
 # Do not generate method or function arguments
@@ -19,9 +20,6 @@ exclude:
     - src/util/util.h
 using_namespace:
   - clanguml
-plantuml:
-  before:
-    - 'title clang-uml main function sequence diagram'
 # Use clang-uml main function as entry point for this diagram
 from:
   - function: main(int,const char **)

uml/sequence/sequence_diagram_visitor_sequence.yml

@@ -1,4 +1,5 @@
 type: sequence
+title: Sequence diagram AST visitor sequence diagram
 # Group free functions into one participant per file
 combine_free_functions_into_file_participants: true
 # Do not generate method or function arguments
@@ -21,8 +22,5 @@ exclude:
     - src/common/model/source_location.h
 using_namespace:
   - clanguml
-plantuml:
-  before:
-    - 'title clang-uml sequence_diagram::visitor::translation_unit_visitor::VisitCXXRecordDecl sequence diagram'
 from:
   - function: "clanguml::sequence_diagram::visitor::translation_unit_visitor::VisitCXXRecordDecl(clang::CXXRecordDecl *)"

uml/sequence/template_builder_sequence.yml

@@ -1,4 +1,5 @@
 type: sequence
+title: Diagram element template builder sequence diagram
 combine_free_functions_into_file_participants: true
 generate_method_arguments: none
 glob:
@@ -14,8 +15,5 @@ exclude:
     - src/common/model/source_location.h
 using_namespace:
   - clanguml
-plantuml:
-  before:
-    - 'title clang-uml class_diagram::visitor::template_builder::build sequence diagram'
 from:
   - function: "clanguml::class_diagram::visitor::template_builder::build(const clang::NamedDecl *,const clang::TemplateSpecializationType &,std::optional<class_diagram::model::class_ *>)"