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

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)
* [Inheritance diagrams](#inheritance-diagrams)
* [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)
* [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
`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
(relative to `using_namespace` property), e.g. `ns1::ns2::MyClass`.
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)
### Directory packages
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
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
> denote the root path against which all relative paths in the config file are
> 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
Sometimes it's helpful to generate a class diagram depicting only direct

60
docs/diagram_filters.md
View File

@@ -3,6 +3,7 @@
<!-- toc -->
* [namespaces](#namespaces)
* [modules](#modules)
* [elements](#elements)
* [element_types](#element_types)
* [paths](#paths)
@@ -12,6 +13,7 @@
* [parents](#parents)
* [specializations](#specializations)
* [access](#access)
* [module_access](#module_access)
* [method_types](#method_types)
* [callee_types](#callee_types)
* [dependants and dependencies](#dependants-and-dependencies)
@@ -56,22 +58,24 @@ exclude:
The following table specifies the values allowed in each filter:
| Filter name | Possible values | Example values |
|-------------------|----------------------------------|------------------------------------------------------------------------------------------------------------------------|
| `namespaces` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: '.*detail.*'``` |
| `elements` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: '.*detail.*'``` |
| `element_types` | Types of diagram elements | ```class```, ```enum```, ```concept``` |
| `paths` | File or dir path or glob pattern | ```src/dir1```, ```src/dir2/a.cpp```, ```src/dir3/*.cpp``` |
| `context` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: 'ns1::ns2::ClassA.+'``` |
| `relationships` | Type of relationship | ```inheritance```, ```composition```, ```aggregation```, ```ownership```, ```association```, ```instantiation```, ```friendship```, ```dependency``` |
| `subclasses` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: 'ns1::ns2::ClassA.+'``` |
| `parents` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: 'ns1::ns2::ClassA.+'``` |
| `specializations` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: 'ns1::ns2::ClassA.+'``` |
| `access` | Method or member access scope | ```public```, ```protected```, ```private``` |
| `method_types` | Type of class method | ```constructor```, ```destructor```, ```assignment```, ```operator```, ```defaulted```, ```deleted```, ```static``` |
| `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``` |
| Filter name | Possible values | Example values |
|-------------------|-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
| `namespaces` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: '.*detail.*'``` |
| `modules` | Qualified name or regex | ```mod1.mod2:par1```, ```r: '.*impl.*'``` |
| `elements` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: '.*detail.*'``` |
| `element_types` | Types of diagram elements | ```class```, ```enum```, ```concept``` |
| `paths` | File or dir path or glob pattern | ```src/dir1```, ```src/dir2/a.cpp```, ```src/dir3/*.cpp``` |
| `context` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: 'ns1::ns2::ClassA.+'``` |
| `relationships` | Type of relationship | ```inheritance```, ```composition```, ```aggregation```, ```ownership```, ```association```, ```instantiation```, ```friendship```, ```dependency``` |
| `subclasses` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: 'ns1::ns2::ClassA.+'``` |
| `parents` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: 'ns1::ns2::ClassA.+'``` |
| `specializations` | Qualified name or regex | ```ns1::ns2::ClassA```, ```r: 'ns1::ns2::ClassA.+'``` |
| `access` | Method or member access scope | ```public```, ```protected```, ```private``` |
| `module_access` | Module access scope | ```public```, ```private``` |
| `method_types` | Type of class method | ```constructor```, ```destructor```, ```assignment```, ```operator```, ```defaulted```, ```deleted```, ```static``` |
| `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:
@@ -88,6 +92,19 @@ Allows to include or exclude entities from specific namespaces.
- 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
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
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`
* `protected`
* `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
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`
* `destructor`
* `assignment`

27
docs/package_diagrams.md
View File

@@ -153,12 +153,31 @@ results the following diagram:
![package_deps](./test_cases/t30002_package.svg)
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
adding the following option to the configuration file:
they can also be generated from the subdirectories in the filesystem tree or
based on C++20 modules
Subdirectory based packages can be enabled by adding the following option to
the configuration file:
```yaml
package_type: directory
```
for example checkout this diagram
![t30011_package](./test_cases/t30011_package.svg)
for example check out this diagram
![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
```