matthias/clang-uml
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Updated docs on C++20 modules

Browse Source
This commit is contained in:
Bartek Kryza
2024-01-11 12:20:27 +01:00
parent 97719e46fc
commit 3fcb00e8eb
4 changed files with 104 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
README.md
View File

@@ -38,6 +38,7 @@ Main features supported so far include:
* Diagram content filtering based on namespaces, elements and relationships - [_example_](docs/test_cases/t00040.md) * Diagram content filtering based on namespaces, elements and relationships - [_example_](docs/test_cases/t00040.md)
* Optional package generation from namespaces (only PlantUML) - [_example_](docs/test_cases/t00036.md) * Optional package generation from namespaces (only PlantUML) - [_example_](docs/test_cases/t00036.md)
* Optional package generation from subdirectories (only PlantUML) - [_example_](docs/test_cases/t00065.md) * Optional package generation from subdirectories (only PlantUML) - [_example_](docs/test_cases/t00065.md)
* Optional package generation from C++20 modules (only PlantUML) - [_example_](docs/test_cases/t00071.md)
* Interactive links to online code or docs for classes, methods and class fields in SVG diagrams - [_example_](https://raw.githubusercontent.com/bkryza/clang-uml/master/docs/test_cases/t00002_class.svg) * Interactive links to online code or docs for classes, methods and class fields in SVG diagrams - [_example_](https://raw.githubusercontent.com/bkryza/clang-uml/master/docs/test_cases/t00002_class.svg)
* Support for plain C99/C11 code (struct, units and their relationships) - [_example_](docs/test_cases/t00057.md) * Support for plain C99/C11 code (struct, units and their relationships) - [_example_](docs/test_cases/t00057.md)
* C++20 concept constraints - [_example_](docs/test_cases/t00059.md) * C++20 concept constraints - [_example_](docs/test_cases/t00059.md)

38
docs/class_diagrams.md
View File

@@ -8,6 +8,9 @@
* [Relationships to classes in containers or smart pointers](#relationships-to-classes-in-containers-or-smart-pointers) * [Relationships to classes in containers or smart pointers](#relationships-to-classes-in-containers-or-smart-pointers)
* [Inheritance diagrams](#inheritance-diagrams) * [Inheritance diagrams](#inheritance-diagrams)
* [Generating UML packages in the diagram](#generating-uml-packages-in-the-diagram) * [Generating UML packages in the diagram](#generating-uml-packages-in-the-diagram)
* [Namespace packages](#namespace-packages)
* [Directory packages](#directory-packages)
* [Module packages](#module-packages)
* [Class context diagram](#class-context-diagram) * [Class context diagram](#class-context-diagram)
* [Disabling dependency relationships](#disabling-dependency-relationships) * [Disabling dependency relationships](#disabling-dependency-relationships)
@@ -132,6 +135,15 @@ rendered. This can be easily achieved in `clang-uml` through inclusion filters:
``` ```
## Generating UML packages in the diagram ## Generating UML packages in the diagram
`clang-uml` supports 3 sources for generating UML packages in a diagram:
* `namespace` - default
* `directory` - based on relative directory paths within the project source tree
* `module` - based on C++20 modules
Currently, a specific diagram can only contain packages of one of the above
types.
### Namespace packages
By default, `clang-uml` will render all element names including a namespace By default, `clang-uml` will render all element names including a namespace
(relative to `using_namespace` property), e.g. `ns1::ns2::MyClass`. (relative to `using_namespace` property), e.g. `ns1::ns2::MyClass`.
In order to generate packages in the diagram for each namespace instead, the In order to generate packages in the diagram for each namespace instead, the
@@ -145,6 +157,7 @@ which results in the following diagram:
![t00036_class](test_cases/t00036_class.svg) ![t00036_class](test_cases/t00036_class.svg)
### Directory packages
In case the code base is structured based on subdirectory instead of namespaces In case the code base is structured based on subdirectory instead of namespaces
(or this is a C project, where namespaces are not available), packages can be (or this is a C project, where namespaces are not available), packages can be
generated based on the location of a given declaration in the filesystem tree, generated based on the location of a given declaration in the filesystem tree,
@@ -162,6 +175,31 @@ which results in the following diagram:
> properly configured for your project, if necessary add `relative_to` option to > properly configured for your project, if necessary add `relative_to` option to
> denote the root path against which all relative paths in the config file are > denote the root path against which all relative paths in the config file are
> calculated. > calculated.
### Module packages
Finally, to generate UML packages in the diagram based on C++20 modules, use
the following option:
```yaml
package_type: module
```
which can produce the following diagram:
![t00071_class](test_cases/t00071_class.svg)
Packages from modules support internal module partitions, which are represented
by `:` prefix in the name as well as conventional submodules separated by `.`.
Module paths can be rendered relative to a specific parent module, to enable
this add the following option:
```yaml
using_module: mod1.mod2
```
which will render modules relative to `mod1.mod2`.
For examples of this feature check out the following test cases documentation:
[t00071](test_cases/t00072.md) and [t00072](test_cases/t00072.md).
## Class context diagram ## Class context diagram
Sometimes it's helpful to generate a class diagram depicting only direct Sometimes it's helpful to generate a class diagram depicting only direct

60
docs/diagram_filters.md
View File

@@ -3,6 +3,7 @@
<!-- toc --> <!-- toc -->
* [namespaces](#namespaces) * [namespaces](#namespaces)
* [modules](#modules)
* [elements](#elements) * [elements](#elements)
* [element_types](#element_types) * [element_types](#element_types)
* [paths](#paths) * [paths](#paths)
@@ -12,6 +13,7 @@
* [parents](#parents) * [parents](#parents)
* [specializations](#specializations) * [specializations](#specializations)
* [access](#access) * [access](#access)
* [module_access](#module_access)
* [method_types](#method_types) * [method_types](#method_types)
* [callee_types](#callee_types) * [callee_types](#callee_types)
* [dependants and dependencies](#dependants-and-dependencies) * [dependants and dependencies](#dependants-and-dependencies)
@@ -56,22 +58,24 @@ exclude:
The following table specifies the values allowed in each filter: The following table specifies the values allowed in each filter:
| Filter name | Possible values | Example values | | Filter name | Possible values | Example values |
|-------------------|----------------------------------|------------------------------------------------------------------------------------------------------------------------| |-------------------|-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
| `namespaces` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: '.*detail.*'``` | | `namespaces` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: '.*detail.*'``` |
| `elements` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: '.*detail.*'``` | | `modules` | Qualified name or regex | ```mod1.mod2:par1```, ```r: '.*impl.*'``` |
| `element_types` | Types of diagram elements | ```class```, ```enum```, ```concept``` | | `elements` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: '.*detail.*'``` |
| `paths` | File or dir path or glob pattern | ```src/dir1```, ```src/dir2/a.cpp```, ```src/dir3/*.cpp``` | | `element_types` | Types of diagram elements | ```class```, ```enum```, ```concept``` |
| `context` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: 'ns1::ns2::ClassA.+'``` | | `paths` | File or dir path or glob pattern | ```src/dir1```, ```src/dir2/a.cpp```, ```src/dir3/*.cpp``` |
| `relationships` | Type of relationship | ```inheritance```, ```composition```, ```aggregation```, ```ownership```, ```association```, ```instantiation```, ```friendship```, ```dependency``` | | `context` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: 'ns1::ns2::ClassA.+'``` |
| `subclasses` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: 'ns1::ns2::ClassA.+'``` | | `relationships` | Type of relationship | ```inheritance```, ```composition```, ```aggregation```, ```ownership```, ```association```, ```instantiation```, ```friendship```, ```dependency``` |
| `parents` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: 'ns1::ns2::ClassA.+'``` | | `subclasses` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: 'ns1::ns2::ClassA.+'``` |
| `specializations` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: 'ns1::ns2::ClassA.+'``` | | `parents` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: 'ns1::ns2::ClassA.+'``` |
| `access` | Method or member access scope | ```public```, ```protected```, ```private``` | | `specializations` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: 'ns1::ns2::ClassA.+'``` |
| `method_types` | Type of class method | ```constructor```, ```destructor```, ```assignment```, ```operator```, ```defaulted```, ```deleted```, ```static``` | | `access` | Method or member access scope | ```public```, ```protected```, ```private``` |
| `dependants` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: 'ns1::ns2::ClassA.+'``` | | `module_access` | Module access scope | ```public```, ```private``` |
| `dependencies` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: 'ns1::ns2::ClassA.+'``` | | `method_types` | Type of class method | ```constructor```, ```destructor```, ```assignment```, ```operator```, ```defaulted```, ```deleted```, ```static``` |
| `callee_types` | Callee types in sequence diagrams| ```constructor```, ```assignment```, ```operator```, ```defaulted```, ```static```, ```method```, ```function```, ```function_template```, ```lambda``` | | `dependants` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: 'ns1::ns2::ClassA.+'``` |
| `dependencies` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: 'ns1::ns2::ClassA.+'``` |
| `callee_types` | Callee types in sequence diagrams | ```constructor```, ```assignment```, ```operator```, ```defaulted```, ```static```, ```method```, ```function```, ```function_template```, ```lambda``` |
The following filters are available: The following filters are available:
@@ -88,6 +92,19 @@ Allows to include or exclude entities from specific namespaces.
- ns1::ns2::detail - ns1::ns2::detail
``` ```
## modules
Allows to include or exclude entities from specific C++20 module.
```yaml
include:
modules:
- mod1.mod2
exclude:
modules:
- r: ".*impl.*"
```
## elements ## elements
Allows to directly include or exclude specific entities from the diagrams, for instance to exclude a specific class Allows to directly include or exclude specific entities from the diagrams, for instance to exclude a specific class
@@ -199,15 +216,22 @@ This filter allows to include or exclude specializations and instantiations of a
## access ## access
This filter allows to include or exclude class methods and members based on their access scope, allowed values ar: This filter allows to include or exclude class methods and members based on their access scope, allowed values are:
* `public` * `public`
* `protected` * `protected`
* `private` * `private`
## module_access
This filter allows to include or exclude diagram elements based on the module in which they are declared, allowed values are:
* `public`
* `private`
## method_types ## method_types
This filter allows to include or exclude various method types from the class diagram, allowed values ar: This filter allows to include or exclude various method types from the class diagram, allowed values are:
* `constructor` * `constructor`
* `destructor` * `destructor`
* `assignment` * `assignment`

27
docs/package_diagrams.md
View File

@@ -153,12 +153,31 @@ results the following diagram:
![package_deps](./test_cases/t30002_package.svg) ![package_deps](./test_cases/t30002_package.svg)
By default, packages are generated from C++ namespaces in the code. However, By default, packages are generated from C++ namespaces in the code. However,
they can also be generated from the subdirectories in the filesystem tree by they can also be generated from the subdirectories in the filesystem tree or
adding the following option to the configuration file: based on C++20 modules
Subdirectory based packages can be enabled by adding the following option to
the configuration file:
```yaml ```yaml
package_type: directory package_type: directory
``` ```
for example checkout this diagram for example check out this diagram
![t30011_package](./test_cases/t30011_package.svg) ![t30011_package](./test_cases/t30011_package.svg)
Module based packages can be enabled using the following option:
```yaml
package_type: module
```
for example check out this diagram
![t30014_package](./test_cases/t30011_package.svg)
Diagrams can be rendered relative to a specific module using `using_module`
option:
```yaml
using_module: mod1.mod2
```