diff --git a/README.md b/README.md index df3c4bef..55031611 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,11 @@ `clang-uml` is an automatic C++ to [PlantUML](https://plantuml.com) class, sequence and package diagram generator, driven by YAML configuration files. The main idea behind the project is to easily maintain up-to-date diagrams within a code-base or document -existing project code. The configuration file or files for `clang-uml` define the +legacy code. The configuration file or files for `clang-uml` define the type and contents of each generated diagram. +`clang-uml` currently supports C++ up to version 17. + ## Features Main features supported so far include: @@ -16,9 +18,9 @@ Main features supported so far include: * Class relationships including associations, aggregations, dependencies and friendship * Template instantiation relationships * Relationship inference from C++ containers and smart pointers - * Namespace based content filtering + * Diagram content filtering based on namespaces, elements and relationships * Optional package generation from namespaces - * Interactive links to online code to classes, methods and class fields + * Interactive links to online code to classes, methods and class fields in SVG diagrams * Sequence diagram generation * Generation of sequence diagram from one code location to another (currently only for non-template code) * Package diagram generation @@ -30,7 +32,7 @@ To see what `clang-uml` can do so far, checkout the diagrams generated for unit ## Installation ### Building from source -Currently the only method to install `clang-uml` is from source. First make sure +Currently, the only method to install `clang-uml` is from source. First make sure that you have the following dependencies installed: ```bash @@ -120,9 +122,9 @@ diagrams: - 'note left of {{ alias("MyProjectMain") }}: Main class of myproject library.' ``` -See ![here](docs/configuration_file.md) for detailed configuration file reference guide. +See [here](docs/configuration_file.md) for detailed configuration file reference guide. -### Examples +## Examples To see what `clang-uml` can do, checkout the test cases documentation [here](./docs/test_cases.md). In order to see diagrams for the `clang-uml` itself, based on its own [config](.clang-uml) run @@ -169,44 +171,6 @@ generates the following diagram (via PlantUML): > Open the raw image [here](https://raw.githubusercontent.com/bkryza/clang-uml/master/docs/test_cases/t00009_class.svg), > and checkout the hover tooltips and hyperlinks to classes and methods. -#### Default mappings - -| UML | C++ | -| ---- | --- | -| Inheritance (A is kind of B) | Public, protected or private inheritance | -| Association (A knows of B) | Class A has a pointer or a reference to class B, or any container with a pointer or reference to B | -| Dependency (A uses B) | Any method of class A has argument of type B | -| Aggregation (A has B) | Class A has a field of type B or an owning pointer of type B | -| Composition (A has B) | Class A has a field of type container of B | -| Template (T specializes A) | Class A has a template parameter T | -| Nesting (A has inner class B) | Class B is an inner class of A -| Friendship (A is a friend of B)| Class A is an friend class of B - -#### Comment decorators - -`clang-uml` provides a set of in-comment directives, called decorators, which allow custom control over -generation of UML diagrams from C++ and overriding default inference rules for relationships. - -The following decorators are currently supported: -- [note](docs/test_cases/t00028.md) - add a PlantUML note to a C++ entity -- [skip](docs/test_cases/t00029.md) - skip the underlying C++ entity -- [skiprelationship](docs/test_cases/t00029.md) - skip only relationship generation for a class property -- [composition](docs/test_cases/t00030.md) - document the property as composition -- [association](docs/test_cases/t00030.md) - document the property as association -- [aggregation](docs/test_cases/t00030.md) - document the property as aggregation -- [style](docs/test_cases/t00031.md) - add PlantUML style to a C++ entity - -##### Doxygen integration -`clang-uml` decorstors can be omitted completely in ![Doxygen](https://www.doxygen.nl/index.html), by adding the following -lines to the Doxygen config file: - -``` -ALIASES += clanguml="" -ALIASES += clanguml{1}="" -ALIASES += clanguml{2}="" -ALIASES += clanguml{3}="" -``` - ### Sequence diagrams #### Example @@ -335,6 +299,73 @@ generates the following diagram (via PlantUML): ![package_diagram_example](docs/test_cases/t30003_package.svg) + +### Default mappings + +| UML | PlantUML | +| ---- | --- | +| Inheritance | ![extension](docs/img/puml_inheritance.png) | +| Association | ![association](docs/img/puml_association.png) | +| Dependency | ![dependency](docs/img/puml_dependency.png) | +| Aggregation | ![aggregation](docs/img/puml_aggregation.png) | +| Composition | ![composition](docs/img/puml_composition.png) | +| Template specialization/instantiation | ![specialization](docs/img/puml_instantiation.png) | +| Nesting (inner class/enum) | ![nesting](docs/img/puml_nested.png) | + +### Diagram content filtering +For typical code bases, generating a single diagram from entire code or even a single namespace can be too big to +be useful, e.g. as part of documentation. `clang-uml` allows specifying content to be included and excluded from +each diagram using simple YAML configuration: + +```yaml +include: + # Include elements from 2 namespaces + namespaces: + - clanguml::common + - clanguml::config + # Include all subclasses of ClassA (including ClassA) + subclasses: + - clanguml::common::ClassA + # Include only inheritance relationships + relationships: + - inheritance + # Include only classes in direct relation to ClassB (including ClassB) + context: + - clanguml::common::ClassB +exclude: + # Exclude all elements from detail namespace + namespaces: + - clanguml::common::detail + # Exclude ClassF + exclude: + - clanguml::common::ClassF +``` + +### Comment decorators + +`clang-uml` provides a set of in-comment directives, called decorators, which allow custom control over +generation of UML diagrams from C++ and overriding default inference rules for relationships. + +The following decorators are currently supported: +- [note](docs/test_cases/t00028.md) - add a PlantUML note to a C++ entity +- [skip](docs/test_cases/t00029.md) - skip the underlying C++ entity +- [skiprelationship](docs/test_cases/t00029.md) - skip only relationship generation for a class property +- [composition](docs/test_cases/t00030.md) - document the property as composition +- [association](docs/test_cases/t00030.md) - document the property as association +- [aggregation](docs/test_cases/t00030.md) - document the property as aggregation +- [style](docs/test_cases/t00031.md) - add PlantUML style to a C++ entity + +### Doxygen integration +`clang-uml` decorstors can be omitted completely in [Doxygen](https://www.doxygen.nl/index.html), by adding the following +lines to the Doxygen config file: + +``` +ALIASES += clanguml="" +ALIASES += clanguml{1}="" +ALIASES += clanguml{2}="" +ALIASES += clanguml{3}="" +``` + ### Test cases The build-in test cases used for unit testing of the `clang-uml`, can be browsed [here](./docs/test_cases.md). diff --git a/docs/img/puml_aggregation.png b/docs/img/puml_aggregation.png new file mode 100644 index 00000000..274fae3e Binary files /dev/null and b/docs/img/puml_aggregation.png differ diff --git a/docs/img/puml_association.png b/docs/img/puml_association.png new file mode 100644 index 00000000..bcb0e9f6 Binary files /dev/null and b/docs/img/puml_association.png differ diff --git a/docs/img/puml_composition.png b/docs/img/puml_composition.png new file mode 100644 index 00000000..083169c9 Binary files /dev/null and b/docs/img/puml_composition.png differ diff --git a/docs/img/puml_dependency.png b/docs/img/puml_dependency.png new file mode 100644 index 00000000..952b3cc4 Binary files /dev/null and b/docs/img/puml_dependency.png differ diff --git a/docs/img/puml_inheritance.png b/docs/img/puml_inheritance.png new file mode 100644 index 00000000..1766929d Binary files /dev/null and b/docs/img/puml_inheritance.png differ diff --git a/docs/img/puml_instantiation.png b/docs/img/puml_instantiation.png new file mode 100644 index 00000000..03616a32 Binary files /dev/null and b/docs/img/puml_instantiation.png differ diff --git a/docs/img/puml_nested.png b/docs/img/puml_nested.png new file mode 100644 index 00000000..8b46286d Binary files /dev/null and b/docs/img/puml_nested.png differ