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

Improved docs (#208)

Browse Source
This commit is contained in:
Bartek Kryza
2023-12-10 21:10:51 +01:00
parent c0faeccff9
commit da6001728b
21 changed files with 173 additions and 150 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
CHANGELOG.md
View File

@@ -1,6 +1,10 @@
# CHANGELOG # CHANGELOG
* Added radius parameter to context filter (#201) * Fixed random typos and omissions in docs (#208)
* Fixed handling of diagram hyperlinks with sources outside of project dir (#213)
* Fixed test case t00014 on macos (#176)
* Added automatic generation of diagram images using PlantUML and MermaidJS (#204)
* Added radius parameter to context filter (#201)
### 0.4.1 ### 0.4.1
* Enabled manual call expression injection through comments (#196) * Enabled manual call expression injection through comments (#196)

6
README.md
View File

@@ -29,7 +29,7 @@ test cases [here](./docs/test_cases.md) or examples in
Main features supported so far include: Main features supported so far include:
* **Class diagram generation** * **Class diagram generation**
* Class properties and methods including access - [_example_](docs/test_cases/t00003.md) * Class properties and methods including access scope - [_example_](docs/test_cases/t00003.md)
* Class inheritance - [_example_](docs/test_cases/t00002.md) * Class inheritance - [_example_](docs/test_cases/t00002.md)
* Other class relationships including associations, aggregations, dependencies and friendship - [_example_](docs/test_cases/t00006.md) * Other class relationships including associations, aggregations, dependencies and friendship - [_example_](docs/test_cases/t00006.md)
* Template instantiation relationships - [_example_](docs/test_cases/t00014.md) * Template instantiation relationships - [_example_](docs/test_cases/t00014.md)
@@ -38,8 +38,8 @@ 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)
* Interactive links to online code to 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 and units 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)
* **Sequence diagram generation** * **Sequence diagram generation**
* Generation of sequence diagram from specific method or function - [_example_](docs/test_cases/t20001.md) * Generation of sequence diagram from specific method or function - [_example_](docs/test_cases/t20001.md)

8
docs/architecture.md
View File

@@ -27,7 +27,7 @@ This section presents general architecture and components of `clang-uml`.
uses [Clang LibTooling API](https://releases.llvm.org/16.0.0/tools/clang/docs/LibTooling.html) uses [Clang LibTooling API](https://releases.llvm.org/16.0.0/tools/clang/docs/LibTooling.html)
to traverse to traverse
the AST (Abstract Syntax Tree) of the source code and extract any information the AST (Abstract Syntax Tree) of the source code and extract any information
relevant for a specified diagram. relevant for a specific diagram.
The code is divided into several packages (namespaces), the main of them are: The code is divided into several packages (namespaces), the main of them are:
@@ -131,11 +131,7 @@ generator.
## Diagram generators ## Diagram generators
Diagram generators convert the `clang-uml`'s internal UML model into actual Diagram generators convert the `clang-uml`'s internal UML model into actual
diagram in one of the supported formats: diagram in one of the supported formats: PlantUML, MermaidJS and JSON.
- PlantUML
- MermaidJS
- JSON
Each diagram generator extends a common interface appropriate for the Each diagram generator extends a common interface appropriate for the
selected output format, i.e.: selected output format, i.e.:

50
docs/class_diagrams.md
View File

@@ -7,7 +7,7 @@
* [Relationships](#relationships) * [Relationships](#relationships)
* [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)
* [Including packages in the diagram](#including-packages-in-the-diagram) * [Generating UML packages in the diagram](#generating-uml-packages-in-the-diagram)
* [Class context diagram](#class-context-diagram) * [Class context diagram](#class-context-diagram)
* [Disabling dependency relationships](#disabling-dependency-relationships) * [Disabling dependency relationships](#disabling-dependency-relationships)
@@ -72,18 +72,18 @@ To render only classes without any properties an exclusion filter can be added:
## Relationships ## Relationships
The following table presents the PlantUML arrows representing each relationship The following table presents the PlantUML and MermaidJS arrows representing each
in the class diagrams. type of relationship generated in the class diagrams.
| UML | PlantUML | | UML | PlantUML | MermaidJS |
| ---- | --- | | ---- | --- |--------------------------------------------|
| Inheritance | ![extension](img/puml_inheritance.png) | | Inheritance | ![extension](img/puml_inheritance.png) | ![extension](img/mermaid_inheritance.png) |
| Association | ![association](img/puml_association.png) | | Association | ![association](img/puml_association.png) | ![extension](img/mermaid_association.png) |
| Dependency | ![dependency](img/puml_dependency.png) | | Dependency | ![dependency](img/puml_dependency.png) | ![extension](img/mermaid_dependency.png) |
| Aggregation | ![aggregation](img/puml_aggregation.png) | | Aggregation | ![aggregation](img/puml_aggregation.png) | ![extension](img/mermaid_aggregation.png) |
| Composition | ![composition](img/puml_composition.png) | | Composition | ![composition](img/puml_composition.png) | ![extension](img/mermaid_composition.png) |
| Template specialization/instantiation | ![specialization](img/puml_instantiation.png) | | Template specialization/instantiation | ![specialization](img/puml_instantiation.png) | ![extension](img/mermaid_instantiation.png) |
| Nesting (inner class/enum) | ![nesting](img/puml_nested.png) | | Nesting (inner class/enum) | ![nesting](img/puml_nested.png) | ![extension](img/mermaid_nested.png) |
By default, a member from which a relationship has been added to the diagram By default, a member from which a relationship has been added to the diagram
@@ -131,7 +131,7 @@ rendered. This can be easily achieved in `clang-uml` through inclusion filters:
- inheritance - inheritance
``` ```
## Including packages in the diagram ## Generating UML packages in the diagram
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,9 +145,10 @@ which results in the following diagram:
![t00036_class](test_cases/t00036_class.svg) ![t00036_class](test_cases/t00036_class.svg)
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
packages can be generated based on the location of a given declaration in the (or this is a C project, where namespaces are not available), packages can be
filesystem tree, by adding also the following option: generated based on the location of a given declaration in the filesystem tree,
by adding also the following option:
```yaml ```yaml
package_type: directory package_type: directory
@@ -173,6 +174,19 @@ this can be easily achieved using `context` inclusion filter:
- ns1::MyClass - ns1::MyClass
``` ```
By default, the diagram will include only elements in direct relationship to
`ns1::MyClass`, but an addition option called `radius` can be added to this
filter, which will extend the context to elements related to `ns1::MyClass`
through at most N relationships, e.g:
```yaml
include:
context:
- match:
radius: 3
pattern: ns1::MyClass
```
## Disabling dependency relationships ## Disabling dependency relationships
Dependency relationships are inferred whenever a class uses another class, thus Dependency relationships are inferred whenever a class uses another class, thus
often dependency relationship will be rendered in addition to other often dependency relationship will be rendered in addition to other
@@ -185,8 +199,8 @@ skip_redundant_dependencies: false
``` ```
In many cases, dependency relationships between classes can clutter the diagram In many cases, dependency relationships between classes can clutter the diagram
too much. In such cases it might be useful to disable dependency relationships too much. In such cases, it might be useful to disable dependency relationships
completely for this diagram completely using the following exclusion filter: completely for this diagram using the following exclusion filter:
```yaml ```yaml
exclude: exclude:
relationships: relationships:

26
docs/common_options.md
View File

@@ -15,8 +15,8 @@
<!-- tocstop --> <!-- tocstop -->
## Overall configuration file structure ## Overall configuration file structure
By default, `clang-uml` will look for file `.clang-uml` in the projects directory and read all diagrams definitions By default, `clang-uml` will look for file `.clang-uml` in the project's directory and read all diagrams definitions
from it. The file must be specified in YAML and it's overall structure is as follows: configuration from it. The file must be specified in YAML and it's overall structure is as follows:
```yaml ```yaml
# common options for all diagrams # common options for all diagrams
@@ -68,16 +68,16 @@ The syntax is simple and based on glob patterns, which can be added to the confi
``` ```
The glob patterns only need to match the translation units, which are also in the `compile_commands.json` file, i.e. The glob patterns only need to match the translation units, which are also in the `compile_commands.json` file, i.e.
any files that match the glob patterns but are not in `compile_commands.json` will be ignored. In case the `glob` any files that match the glob patterns, but are not in `compile_commands.json` will be ignored. In case the `glob`
pattern set does not match any translation units an error will be printed on the standard output. pattern set does not match any translation units an error will be printed on the standard output.
For small projects, the `glob` property can be omitted, which will result in `clang-uml` parsing all translation units For small projects, the `glob` property can be omitted, which will result in `clang-uml` parsing all translation units
from `compile_commands.json` for the diagram. However for large projects, constraining the number of translation units from `compile_commands.json` for the diagram. However, for large projects, constraining the number of translation units
for each diagram to absolute minimum will significantly decrease the diagram generation times. for each diagram to absolute minimum will significantly decrease the diagram generation times.
## Custom directives ## Custom directives
In case it's necessary to add some custom PlantUML or MermaidJS declarations In case it's necessary to add some custom PlantUML or MermaidJS declarations
before or after the generated diagram content, it can be achieved simply using before or after the generated diagram content, it can be achieved using
the `plantuml` or `mermaid` configuration properties, for instance for PlantUML: the `plantuml` or `mermaid` configuration properties, for instance for PlantUML:
```yaml ```yaml
@@ -98,11 +98,12 @@ or for MermaidJS:
- note for {{ alias("ns1::ns2::MyClass") }} "This is my class." - note for {{ alias("ns1::ns2::MyClass") }} "This is my class."
``` ```
These directive are useful for instance for adding notes to elements in the These directives are useful for instance for adding notes to elements in the
diagrams or customizing diagram layout or style. diagrams or customizing diagram layout and style.
Please note that when referring to diagram elements in the PlantUML directives, Please note that when referring to diagram elements in PlantUML or MermaidJS
they must be added using Jinja templates `alias` command as in the example above. directives, they must be added using Jinja templates `alias` command as in the
example above.
More options can be found in the official docs for each respective generator: More options can be found in the official docs for each respective generator:
* [PlantUML](https://plantuml.com/) * [PlantUML](https://plantuml.com/)
@@ -118,8 +119,7 @@ debug_mode: true
``` ```
the generated PlantUML diagram will contain comments before each line containing the generated PlantUML diagram will contain comments before each line containing
the source location of the the source location of the specific diagram element.
specific diagram element.
## Resolving include path and compiler flags issues ## Resolving include path and compiler flags issues
Due to the fact, that your project can be compiled with different compilers Due to the fact, that your project can be compiled with different compilers
@@ -175,8 +175,8 @@ command:
``` ```
If you want to include the system headers reported by the compiler specified If you want to include the system headers reported by the compiler specified
already as `argv[0]` in your `compile_commands.json`, you can simply invoke already as first argument of each compile command in your
`clang-uml` as: `compile_commands.json`, you can simply invoke `clang-uml` as:
```bash ```bash
clang-uml --query-driver . clang-uml --query-driver .

72
docs/diagram_filters.md
View File

@@ -41,10 +41,10 @@ Some filters accept either specified exact values, some support regular
expressions while some except glob patterns. expressions while some except glob patterns.
For filters which accept regular expressions, the regular expression has to For filters which accept regular expressions, the regular expression has to
be provided as a map `r: 'pattern'` due to the fact the pointer (`*`) otherwise be provided as a map ```r: 'pattern'``` due to the fact the pointer (```*```) otherwise
would have to be escaped in situations such as `mycontainer<char*>`, so for would have to be escaped in situations such as ```mycontainer<char*>```, so for
instance to specify that the diagram should exclude all classes containing the instance to specify that the diagram should exclude all classes containing the
word `test` simply add the following filter: word ```test``` simply add the following filter:
```yaml ```yaml
exclude: exclude:
@@ -73,12 +73,21 @@ The following table specifies the values allowed in each filter:
| `dependencies` | 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``` | | `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:
## namespaces ## namespaces
Allows to include or exclude entities from specific namespaces. Allows to include or exclude entities from specific namespaces.
```yaml
include:
namespaces:
- ns1::ns2
exclude:
namespaces:
- ns1::ns2::detail
```
## 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
@@ -113,10 +122,11 @@ in specific files.
diagrams: diagrams:
t00061_class: t00061_class:
type: class type: class
relative_to: ../../tests/t00061 glob:
glob: [t00061.cc] - t00061.cc
include: include:
paths: [include/t00061_a.h] paths:
- include/t00061_a.h
using_namespace: using_namespace:
- clanguml::t00061 - clanguml::t00061
``` ```
@@ -166,14 +176,14 @@ include inheritance and template specialization/instantiation relationships add
``` ```
The following relationships can be used in this filter: The following relationships can be used in this filter:
* inheritance * `inheritance`
* composition * `composition`
* aggregation * `aggregation`
* ownership * `ownership`
* association * `association`
* instantiation * `instantiation`
* friendship * `friendship`
* dependency * `dependency`
## subclasses ## subclasses
@@ -198,13 +208,13 @@ This filter allows to include or exclude class methods and members based on thei
## 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 ar:
* constructor * `constructor`
* destructor * `destructor`
* assignment * `assignment`
* operator * `operator`
* defaulted * `defaulted`
* deleted * `deleted`
* static * `static`
This filter is independent of the `access` filter, which controls which methods This filter is independent of the `access` filter, which controls which methods
are included based on access scope (e.g. `public`). are included based on access scope (e.g. `public`).
@@ -217,15 +227,15 @@ a `callee` is the receiver of a message, and this filter specifies which types
of receivers should match. of receivers should match.
The following callee types are supported: The following callee types are supported:
* constructor * `constructor`
* assignment * `assignment`
* operator * `operator`
* defaulted * `defaulted`
* static * `static`
* method * `method`
* function * `function`
* function_template * `function_template`
* lambda * `lambda`
## dependants and dependencies ## dependants and dependencies

2
docs/generator_types.md
View File

@@ -12,7 +12,7 @@ Currently, there are 3 types of diagram generators: `plantuml`, `mermaid`
and `json`. and `json`.
To specify, which generators should be used on the command line use option `-g`. To specify, which generators should be used on the command line use option `-g`.
For instance to generate both types of diagrams run `clang-uml` as follows: For instance to generate all types of diagrams run `clang-uml` as follows:
```bash ```bash
clang-uml -g plantuml -g mermaid -g json clang-uml -g plantuml -g mermaid -g json

BIN
docs/img/mermaid_aggregation.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.1 KiB

After

Width:  |  Height:  |  Size: 7.0 KiB

BIN
docs/img/mermaid_association.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 772 B

After

Width:  |  Height:  |  Size: 6.0 KiB

BIN
docs/img/mermaid_composition.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 867 B

After

Width:  |  Height:  |  Size: 6.3 KiB

BIN
docs/img/mermaid_dependency.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.0 KiB

After

Width:  |  Height:  |  Size: 6.9 KiB

BIN
docs/img/mermaid_inheritance.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.1 KiB

After

Width:  |  Height:  |  Size: 6.8 KiB

BIN
docs/img/mermaid_instantiation.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.3 KiB

After

Width:  |  Height:  |  Size: 7.5 KiB

BIN
docs/img/mermaid_nested.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 976 B

After

Width:  |  Height:  |  Size: 6.6 KiB

42
docs/include_diagrams.md
View File

@@ -6,17 +6,13 @@
<!-- tocstop --> <!-- tocstop -->
Include diagrams allow to document the include dependencies among different parts of the project. This can be very useful Include diagrams allow to document the include dependencies among different
for instance to detect that a file was included from a module directory, on which specific part of the project parts of the project. This can be very useful for instance to detect that a file
should not ever depend. was included from a module directory, on which specific part of the project
should never depend.
The minimal config required to generate an include diagram is presented below: The minimal config required to generate an include diagram is presented below:
```yaml ```yaml
# Path to the directory where `compile_commands.json` can be found
compilation_database_dir: _build
# Output directory for the diagrams
output_directory: diagrams
# Diagrams definitions
diagrams: diagrams:
# Diagram name # Diagram name
my_class_diagram: my_class_diagram:
@@ -25,8 +21,6 @@ diagrams:
# Include only translation units matching the following patterns # Include only translation units matching the following patterns
glob: glob:
- src/*.cc - src/*.cc
# Render the paths relative to this directory
relative_to: src
# Include also external system headers # Include also external system headers
generate_system_headers: true generate_system_headers: true
# Include only classes and functions from files in `src` directory # Include only classes and functions from files in `src` directory
@@ -36,29 +30,31 @@ diagrams:
- src - src
``` ```
One distinctive option in `include` diagrams is `relative_to`, which tells `clang-uml` to render all filename One distinctive option in `include` diagrams is `relative_to`, which tells
paths relative to this directory. `clang-uml` to render all filename paths relative to this directory.
The following table presents the PlantUML arrows representing relationships in the include diagrams. The following table presents the PlantUML arrows representing relationships in
the include diagrams.
| UML | PlantUML | | UML | PlantUML | MermaidJS |
| ---- | --- | |-----------------------------------------|------------------------------------------|---------------------------------------------|
| Include (local) | ![association](img/puml_association.png) | | Include (local) | ![association](img/puml_association.png) | ![association](img/mermaid_association.png) |
| Include (system) | ![dependency](img/puml_dependency.png) | | Include (system) | ![dependency](img/puml_dependency.png) | ![association](img/mermaid_dependency.png) |
## Tracking system headers directly included by project sources ## Tracking system headers directly included by project sources
In case you would like to include the information about what system headers your projects file include simply add In case you would like to include the information about what system headers your
the following option to the diagram: project files include simply add the following option to the diagram:
```yaml ```yaml
generate_system_headers: true generate_system_headers: true
``` ```
This will include only system headers directly included from the projects source files (matched by `glob`) and not This will include only system headers directly included from the project's
their dependencies, for example: source files (matched by `glob`) and not their dependencies, for example:
![t40001_include](./test_cases/t40001_include.svg) ![t40001_include](./test_cases/t40001_include.svg)
Please note that generating include diagram, which contains third party and system library headers will result Please note that generating include diagram, which contains third party and
in a huge diagram that will be unlikely to be useful. system library headers will result in a huge diagram that will be unlikely to
be useful.

11
docs/installation.md
View File

@@ -64,8 +64,8 @@ Download and run the latest Windows installer from
First make sure that you have the following dependencies installed: First make sure that you have the following dependencies installed:
```bash ```bash
# Ubuntu (clang version will vary depending on Ubuntu version) # Ubuntu (Clang version will vary depending on Ubuntu version - below example is for Ubuntu 22.04)
apt install ccache cmake libyaml-cpp-dev clang-12 libclang-12-dev libclang-cpp12-dev apt install make gcc g++ ccache cmake libyaml-cpp-dev llvm-15 clang-15 libclang-15-dev libclang-cpp15-dev clang-format-15
``` ```
Then proceed with building the sources: Then proceed with building the sources:
@@ -81,6 +81,9 @@ release/src/clang-uml --help
LLVM_VERSION=16 make release LLVM_VERSION=16 make release
# or specify path to a specific llvm-config binary, e.g.: # or specify path to a specific llvm-config binary, e.g.:
LLVM_CONFIG_PATH=/usr/bin/llvm-config-16 make release LLVM_CONFIG_PATH=/usr/bin/llvm-config-16 make release
# or directly specify the path where LLVMConfig.cmake can be found on your system, e.g.:
CMAKE_PREFIX=/usr/lib/llvm-16/lib/cmake/llvm make release
# Optionally, to install in default prefix # Optionally, to install in default prefix
make install make install
@@ -96,8 +99,10 @@ export PATH=$PATH:$PWD/release
brew install ccache cmake llvm yaml-cpp brew install ccache cmake llvm yaml-cpp
export CC=/usr/local/opt/llvm/bin/clang export CC=/usr/local/opt/llvm/bin/clang
export CCX=/usr/local/opt/llvm/bin/clang++ export CXX=/usr/local/opt/llvm/bin/clang++
LLVM_VERSION=16 make release LLVM_VERSION=16 make release
# or, if this fails, try:
CMAKE_PREFIX=/usr/local/opt/llvm/lib/cmake/llvm make release
``` ```
#### Windows #### Windows

10
docs/interactive_svg_diagrams.md
View File

@@ -6,13 +6,13 @@
<!-- tocstop --> <!-- tocstop -->
`clang-uml` in combination with PlantUML's link generation in diagrams allows to `clang-uml` in combination with PlantUML and MermaidJS link generation in
generate interactive diagrams, where clicking on any class, method or call diagrams allows to generate interactive diagrams, where clicking on any class,
expression can direct the user directly to the source code or some other method or call expression can direct the user directly to the source code or
diagram or document available online. some other diagram or document available online.
For instance to generate links to GitHub repository directly for most diagram For instance to generate links to GitHub repository directly for most diagram
elements simple add this to your `.clang-uml` file: elements simply add this to your `.clang-uml` file:
```yaml ```yaml
generate_links: generate_links:

7
docs/package_diagrams.md
View File

@@ -7,16 +7,11 @@
<!-- tocstop --> <!-- tocstop -->
Package diagrams are simple diagrams, which can be useful to visualize a high Package diagrams are simple diagrams, which can be useful to visualize a high
level structure of a C++ project, by rendering all projects namespaces or level structure of a C++ project, by rendering project's namespaces or
subdirectories as UML packages and their interdependencies. subdirectories as UML packages and their interdependencies.
The minimal config required to generate a package diagram is presented below: The minimal config required to generate a package diagram is presented below:
```yaml ```yaml
# Path to the directory where `compile_commands.json` can be found
compilation_database_dir: _build
# Output directory for the diagrams
output_directory: diagrams
# Diagrams definitions
diagrams: diagrams:
# Diagram name # Diagram name
my_class_diagram: my_class_diagram:

8
docs/quick_start.md
View File

@@ -8,7 +8,7 @@
To add an initial class diagram to your project, follow these steps: To add an initial class diagram to your project, follow these steps:
1. Enter your projects top level directory and run: 1. Enter your project's top level directory and run:
```bash ```bash
clang-uml --init clang-uml --init
``` ```
@@ -36,10 +36,10 @@ To add an initial class diagram to your project, follow these steps:
namespaces: namespaces:
- myproject::detail - myproject::detail
``` ```
3. Run `clang-uml` in the projects top directory: 3. Run `clang-uml` in the project's top directory:
```bash ```bash
clang-uml clang-uml
# or to see generation progress for each diagram run # or to see generation progress for each diagram
clang-uml --progress clang-uml --progress
``` ```
4. Generate SVG images from the PlantUML diagrams: 4. Generate SVG images from the PlantUML diagrams:
@@ -62,7 +62,7 @@ To add an initial class diagram to your project, follow these steps:
```bash ```bash
clang-uml --add-sequence-diagram another_diagram clang-uml --add-sequence-diagram another_diagram
``` ```
6. Now list the diagrams defined in the config: 6. Now list the diagrams defined in the config file:
```bash ```bash
clang-uml -l clang-uml -l
The following diagrams are defined in the config file: The following diagrams are defined in the config file:

41
docs/sequence_diagrams.md
View File

@@ -55,23 +55,23 @@ C++ code, the following assumptions were made:
from plain old C code). Functions can also be aggregated into file from plain old C code). Functions can also be aggregated into file
participants, based on their place of declaration participants, based on their place of declaration
* Call expressions in conditional expressions in block statements (e.g. `if` * Call expressions in conditional expressions in block statements (e.g. `if`
or `while`) are rendered inside the PlantUML `alt` or `loop` blocks but or `while`) are rendered inside the PlantUML or MermaidJS `alt` or `loop`
wrapped in `[`, `]` brackets blocks but wrapped in `[`, `]` brackets
* Lambda expressions are generated as standalone participants, whose name * Lambda expressions are generated as standalone participants, whose name
comprises the parent context where they are defined and the exact source code comprises the parent context where they are defined and the exact source code
location location
## Specifying diagram location constraints ## Specifying diagram location constraints
Sequence diagrams require a specification of location constraints in order to Sequence diagrams require specification of location constraints in order to
determine, which call chains should be included in the diagram. Currently, determine, which call chains should be included in the diagram. Currently,
there are 3 types of constraints: there are 3 types of constraints:
* `from` - will include all message call chains which start at the * `from` - will include all message call chains, which start at the
locations specified in this constraint (this was previously named locations specified in this constraint (this was previously named
`start_from`) `start_from`)
* `to` - will include all message call chains which end at the specified * `to` - will include all message call chains, which end at the specified
locations locations
* `from_to` - will include all call chains which start and end at the specified * `from_to` - will include all call chains, which start and end at the specified
location constraints locations
Currently, the constraints can be a method or a free function, both specified Currently, the constraints can be a method or a free function, both specified
using the full signature of the function, e.g. using the full signature of the function, e.g.
@@ -97,7 +97,7 @@ and `to` locations as follows:
function: "clanguml::t20034::A::a2()"] function: "clanguml::t20034::A::a2()"]
``` ```
To find the exact function signature which can be used as a `from` location, To find the exact function signature which, can be used as a `from` location,
run `clang-uml` as follows: run `clang-uml` as follows:
```bash ```bash
@@ -255,18 +255,16 @@ results in the following diagram:
## Customizing participants order ## Customizing participants order
The default participant order in the sequence diagram can be suboptimal in the The default participant order in the sequence diagram can be suboptimal in the
sense that consecutive calls can go right, then left, then right again sense that consecutive calls can go right, then left, then right again
depending on the specific call chain in the code. It is however depending on the specific call chain in the code. It is however possible to
possible to override this order in the diagram definition using override this order in the diagram definition using `participants_order`
`participants_order` property, for instance like this test case: property, for instance like this test case:
```yaml ```yaml
compilation_database_dir: ..
output_directory: diagrams
diagrams: diagrams:
t20029_sequence: t20029_sequence:
type: sequence type: sequence
glob: glob:
- ../../tests/t20029/t20029.cc - t20029.cc
include: include:
namespaces: namespaces:
- clanguml::t20029 - clanguml::t20029
@@ -296,13 +294,12 @@ following configuration option:
generate_return_types: true generate_return_types: true
``` ```
This option only affects the `plantuml` generation, in `json` generator This option only affects the `plantuml` and `mermaid` generators, in `json`
`return_type` property is always present in the message nodes. generator `return_type` property is always present in the message nodes.
The diagram below presents what it looks like in a PlantUML generated diagram: The diagram below presents what it looks like in a PlantUML generated diagram:
![extension](test_cases/t20032_sequence.svg) ![extension](test_cases/t20032_sequence.svg)
## Generating condition statements ## Generating condition statements
Sometimes, it is useful to include actual condition statements (for instance Sometimes, it is useful to include actual condition statements (for instance
contents of the `if()` condition in the `alt` or `loop` blocks in the sequence contents of the `if()` condition in the `alt` or `loop` blocks in the sequence
@@ -323,8 +320,12 @@ in some line of code. This can include passing function or method address to
some executor (e.g. thread), async calls etc. some executor (e.g. thread), async calls etc.
However, a call expression can be injected manually through a comment However, a call expression can be injected manually through a comment
directive `\uml{note CALLEE}`, when placed just before such line of code, for directive
example: ```cpp
// \uml{note CALLEE}
```
It should be placed in the comment just before such line of code, for example:
```cpp ```cpp
// \uml{call clanguml::t20038::B::bbb()} // \uml{call clanguml::t20038::B::bbb()}
@@ -346,7 +347,7 @@ add_compile_flags:
otherwise Clang will skip these comments during AST traversal. otherwise Clang will skip these comments during AST traversal.
## Including comments in sequence diagrams ## Including comments in sequence diagrams
`clang-uml` can add code comments placed directly before are next to a call `clang-uml` can add code comments placed directly before or next to a call
expression as notes in the diagram (see for instance expression as notes in the diagram (see for instance
[t20038](test_cases/t20038_sequence.svg)). [t20038](test_cases/t20038_sequence.svg)).

32
docs/troubleshooting.md
View File

@@ -9,7 +9,7 @@
* [Clang produces several warnings during diagram generation](#clang-produces-several-warnings-during-diagram-generation) * [Clang produces several warnings during diagram generation](#clang-produces-several-warnings-during-diagram-generation)
* [Cannot generate diagrams from header-only projects](#cannot-generate-diagrams-from-header-only-projects) * [Cannot generate diagrams from header-only projects](#cannot-generate-diagrams-from-header-only-projects)
* [YAML anchors and aliases are not fully supported](#yaml-anchors-and-aliases-are-not-fully-supported) * [YAML anchors and aliases are not fully supported](#yaml-anchors-and-aliases-are-not-fully-supported)
* [Schema validation error is thrown, but the configuration file is correct](#schema-validation-error-is-thrown-but-the-configuration-file-is-correct) * [Schema validation error is thrown, but the configuration file is correct](#schema-validation-error-is-thrown-but-the-configuration-file-is-correct)
* [Class diagrams](#class-diagrams) * [Class diagrams](#class-diagrams)
* ["fatal error: 'stddef.h' file not found"](#fatal-error-stddefh-file-not-found) * ["fatal error: 'stddef.h' file not found"](#fatal-error-stddefh-file-not-found)
* [How can I generate class diagram of my entire project](#how-can-i-generate-class-diagram-of-my-entire-project) * [How can I generate class diagram of my entire project](#how-can-i-generate-class-diagram-of-my-entire-project)
@@ -27,7 +27,7 @@
If `clang-uml` crashes with a segmentation fault, it is possible to trace the If `clang-uml` crashes with a segmentation fault, it is possible to trace the
exact stack trace of the fault using the following steps: exact stack trace of the fault using the following steps:
First, build `clang-uml` from source in debug mode, e.g.: First, build `clang-uml` from source in debug mode, i.e.:
```bash ```bash
make debug make debug
@@ -35,15 +35,16 @@ make debug
Then run `clang-uml`, preferably with `-vvv` for verbose log output. If your Then run `clang-uml`, preferably with `-vvv` for verbose log output. If your
`.clang-uml` configuration file contains more than 1 diagram, specify only `.clang-uml` configuration file contains more than 1 diagram, specify only
a single diagram to make it easier to trace the root cause of the crash, e.g.: the diagram causing the crash, to make it easier to trace the root cause of
the crash, e.g.:
```bash ```bash
debug/src/clang-uml -vvv -n my_diagram debug/src/clang-uml -vvv -n my_diagram
``` ```
After `clang-uml` crashes again, detailed backtrace (generated using After `clang-uml` crashes again, detailed backtrace (generated using
[backward-cpp](https://github.com/bombela/backward-cpp)) should be visible [backward-cpp](https://github.com/bombela/backward-cpp) library) should be
on the console. visible on the console.
If possible, [create an issue](https://github.com/bkryza/clang-uml/issues) and If possible, [create an issue](https://github.com/bkryza/clang-uml/issues) and
paste the stack trace and few last logs from the console. paste the stack trace and few last logs from the console.
@@ -52,8 +53,7 @@ paste the stack trace and few last logs from the console.
`clang-uml` uses `clang-uml` uses
Clang's [RecursiveASTVisitor](https://clang.llvm.org/doxygen/classclang_1_1RecursiveASTVisitor.html), Clang's [RecursiveASTVisitor](https://clang.llvm.org/doxygen/classclang_1_1RecursiveASTVisitor.html),
to to traverse the source code. By default, this visitor is invoked on every
traverse the source code. By default, this visitor is invoked on every
translation unit (i.e. each entry in your `compile_commands.json`), including translation unit (i.e. each entry in your `compile_commands.json`), including
all of their header dependencies recursively. This means, that for large code all of their header dependencies recursively. This means, that for large code
bases with hundreds or thousands of translation units, traversing all of them bases with hundreds or thousands of translation units, traversing all of them
@@ -201,7 +201,7 @@ the configuration file to `clang-uml` using `stdin`, e.g.:
yq 'explode(.)' .clang-uml | clang-uml --config - yq 'explode(.)' .clang-uml | clang-uml --config -
``` ```
## Schema validation error is thrown, but the configuration file is correct ### Schema validation error is thrown, but the configuration file is correct
Current version of `clang-uml` performs automatic configuration file Current version of `clang-uml` performs automatic configuration file
schema validation, and exits if the configuration file is invalid. schema validation, and exits if the configuration file is invalid.
@@ -325,11 +325,10 @@ Hopefully this will be eventually resolved.
### Generated diagram is empty ### Generated diagram is empty
In order to generate sequence diagram the `start_from` configuration option must In order to generate sequence diagram the location constraints (`from`, `to`
have a valid starting point or `from_to`) in configuration file must point to valid locations in the code
for the diagram (e.g. `function`), which must match exactly the function for the diagram (e.g. `function`), which must match exactly the function
or method signature in the `clang-uml` diagram model. or method signature in the `clang-uml` diagram model.
Look for error in the console output such as: Look for error in the console output such as:
```bash ```bash
@@ -341,16 +340,19 @@ configuration file, or that the function
was not defined in the translation units you specified in the `glob` patterns was not defined in the translation units you specified in the `glob` patterns
for this diagram. for this diagram.
Except for simplest methods and functions, it is unlikely to write by hand
the exact string representation of the function signature as seen by `clang-uml`.
To find the exact function signature run `clang-uml` as follows: To find the exact function signature run `clang-uml` as follows:
```bash ```bash
clang-uml -n my_sequence_diagram --print-start-from | grep foo clang-uml -n my_sequence_diagram --print-start-from | grep foo
``` ```
Command line flag `--print-start-from` will print on stdout all functions Command line flag `--print-from` will print on stdout all functions
and methods available in the diagram model, and each line of this output and methods available in the diagram model which can be used as starting
can be directly used as a value of `start_from` option in the config file. points for a sequence diagram (similarly `--print-to` can be used to list
all valid functions to be used as call chain end constraints).
### Generated diagram contains several empty control blocks or calls which should not be there ### Generated diagram contains several empty control blocks or calls which should not be there