Merge pull request #184 from bkryza/add-title-property

Added 'title' diagram property
This commit is contained in:
Bartek Kryza
2023-10-09 16:05:36 +02:00
committed by GitHub
52 changed files with 173 additions and 66 deletions

View File

@@ -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.

View File

@@ -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);

View File

@@ -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

View File

@@ -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

View File

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

View File

@@ -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
#

View File

@@ -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;
}

View File

@@ -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;
}

View File

@@ -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

View File

@@ -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")));

View File

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

View File

@@ -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)"));

View File

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

View File

@@ -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")));

View File

@@ -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:

View File

@@ -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")));

View File

@@ -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));

View File

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

View File

@@ -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
plantuml:
before:
- 'title clang-uml class diagram model'
- clanguml

View File

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

View File

@@ -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'

View File

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

View File

@@ -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.'

View File

@@ -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
plantuml:
before:
- 'title clanguml::config::config context diagram'
- clanguml::config

View File

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

View File

@@ -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
plantuml:
before:
- 'title clang-uml decorators model'
- clanguml::decorators

View File

@@ -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
plantuml:
before:
- 'title clanguml::config::diagram class hierarchy'
- clanguml

View File

@@ -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
plantuml:
before:
- 'title clang-uml diagram element class inheritance model'
- clanguml

View File

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

View File

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

View File

@@ -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
plantuml:
before:
- 'title clang-uml diagram model'
- clanguml

View File

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

View File

@@ -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

View File

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

View File

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

View File

@@ -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
plantuml:
before:
- 'title clang-uml package diagram model'
- dependency

View File

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

View File

@@ -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
plantuml:
before:
- 'title clang-uml sequence diagram model'
- clanguml

View File

@@ -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

View File

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

View File

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

View File

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

View File

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

View File

@@ -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"
plantuml:
before:
- 'title clang-uml top level packages'
- r: "clanguml::.+::generators"

View File

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

View File

@@ -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"

View File

@@ -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

View File

@@ -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:

View File

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

View File

@@ -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 **)

View File

@@ -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 *)"

View File

@@ -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_ *>)"