From 3fcb00e8eb38e5b9b76eaf306048df16b2727330 Mon Sep 17 00:00:00 2001 From: Bartek Kryza Date: Thu, 11 Jan 2024 12:20:27 +0100 Subject: [PATCH] Updated docs on C++20 modules --- README.md | 1 + docs/class_diagrams.md | 38 +++++++++++++++++++++++++ docs/diagram_filters.md | 60 ++++++++++++++++++++++++++++------------ docs/package_diagrams.md | 27 +++++++++++++++--- 4 files changed, 104 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 67741c32..1b0d3cec 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/docs/class_diagrams.md b/docs/class_diagrams.md index a652f2dd..ac6a670b 100644 --- a/docs/class_diagrams.md +++ b/docs/class_diagrams.md @@ -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 diff --git a/docs/diagram_filters.md b/docs/diagram_filters.md index 3bfd9f38..759b7c49 100644 --- a/docs/diagram_filters.md +++ b/docs/diagram_filters.md @@ -3,6 +3,7 @@ * [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` diff --git a/docs/package_diagrams.md b/docs/package_diagrams.md index 5e542be2..952436c6 100644 --- a/docs/package_diagrams.md +++ b/docs/package_diagrams.md @@ -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) \ No newline at end of file +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 +```