Improved docs (#208)
This commit is contained in:
Bartek Kryza
@@ -1,6 +1,10 @@
|
||||
# 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
|
||||
* Enabled manual call expression injection through comments (#196)
|
||||
|
||||
@@ -29,7 +29,7 @@ test cases [here](./docs/test_cases.md) or examples in
|
||||
Main features supported so far include:
|
||||
|
||||
* **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)
|
||||
* Other class relationships including associations, aggregations, dependencies and friendship - [_example_](docs/test_cases/t00006.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)
|
||||
* 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)
|
||||
* 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)
|
||||
* Support for plain C99/C11 code (struct and units relationships) - [_example_](docs/test_cases/t00057.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)
|
||||
* **Sequence diagram generation**
|
||||
* Generation of sequence diagram from specific method or function - [_example_](docs/test_cases/t20001.md)
|
||||
|
||||
@@ -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)
|
||||
to traverse
|
||||
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:
|
||||
|
||||
@@ -131,11 +131,7 @@ generator.
|
||||
## Diagram generators
|
||||
|
||||
Diagram generators convert the `clang-uml`'s internal UML model into actual
|
||||
diagram in one of the supported formats:
|
||||
|
||||
- PlantUML
|
||||
- MermaidJS
|
||||
- JSON
|
||||
diagram in one of the supported formats: PlantUML, MermaidJS and JSON.
|
||||
|
||||
Each diagram generator extends a common interface appropriate for the
|
||||
selected output format, i.e.:
|
||||
|
||||
@@ -7,7 +7,7 @@
|
||||
* [Relationships](#relationships)
|
||||
* [Relationships to classes in containers or smart pointers](#relationships-to-classes-in-containers-or-smart-pointers)
|
||||
* [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)
|
||||
* [Disabling dependency relationships](#disabling-dependency-relationships)
|
||||
|
||||
@@ -72,18 +72,18 @@ To render only classes without any properties an exclusion filter can be added:
|
||||
|
||||
## Relationships
|
||||
|
||||
The following table presents the PlantUML arrows representing each relationship
|
||||
in the class diagrams.
|
||||
The following table presents the PlantUML and MermaidJS arrows representing each
|
||||
type of relationship generated in the class diagrams.
|
||||
|
||||
| UML | PlantUML |
|
||||
| ---- | --- |
|
||||
| Inheritance |  |
|
||||
| Association |  |
|
||||
| Dependency |  |
|
||||
| Aggregation |  |
|
||||
| Composition |  |
|
||||
| Template specialization/instantiation |  |
|
||||
| Nesting (inner class/enum) |  |
|
||||
| UML | PlantUML | MermaidJS |
|
||||
| ---- | --- |--------------------------------------------|
|
||||
| Inheritance |  |  |
|
||||
| Association |  |  |
|
||||
| Dependency |  |  |
|
||||
| Aggregation |  |  |
|
||||
| Composition |  |  |
|
||||
| Template specialization/instantiation |  |  |
|
||||
| Nesting (inner class/enum) |  |  |
|
||||
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
## Including packages in the diagram
|
||||
## Generating UML packages in the diagram
|
||||
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,9 +145,10 @@ which results in the following diagram:
|
||||
|
||||
|
||||
|
||||
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
|
||||
filesystem tree, by adding also the following option:
|
||||
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,
|
||||
by adding also the following option:
|
||||
|
||||
```yaml
|
||||
package_type: directory
|
||||
@@ -173,6 +174,19 @@ this can be easily achieved using `context` inclusion filter:
|
||||
- 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
|
||||
Dependency relationships are inferred whenever a class uses another class, thus
|
||||
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
|
||||
too much. In such cases it might be useful to disable dependency relationships
|
||||
completely for this diagram completely using the following exclusion filter:
|
||||
too much. In such cases, it might be useful to disable dependency relationships
|
||||
completely for this diagram using the following exclusion filter:
|
||||
```yaml
|
||||
exclude:
|
||||
relationships:
|
||||
|
||||
@@ -15,8 +15,8 @@
|
||||
<!-- tocstop -->
|
||||
|
||||
## Overall configuration file structure
|
||||
By default, `clang-uml` will look for file `.clang-uml` in the projects directory and read all diagrams definitions
|
||||
from it. The file must be specified in YAML and it's overall structure is as follows:
|
||||
By default, `clang-uml` will look for file `.clang-uml` in the project's directory and read all diagrams definitions
|
||||
configuration from it. The file must be specified in YAML and it's overall structure is as follows:
|
||||
|
||||
```yaml
|
||||
# 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.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## Custom directives
|
||||
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:
|
||||
|
||||
```yaml
|
||||
@@ -98,11 +98,12 @@ or for MermaidJS:
|
||||
- note for {{ alias("ns1::ns2::MyClass") }} "This is my class."
|
||||
```
|
||||
|
||||
These directive are useful for instance for adding notes to elements in the
|
||||
diagrams or customizing diagram layout or style.
|
||||
These directives are useful for instance for adding notes to elements in the
|
||||
diagrams or customizing diagram layout and style.
|
||||
|
||||
Please note that when referring to diagram elements in the PlantUML directives,
|
||||
they must be added using Jinja templates `alias` command as in the example above.
|
||||
Please note that when referring to diagram elements in PlantUML or MermaidJS
|
||||
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:
|
||||
* [PlantUML](https://plantuml.com/)
|
||||
@@ -118,8 +119,7 @@ debug_mode: true
|
||||
```
|
||||
|
||||
the generated PlantUML diagram will contain comments before each line containing
|
||||
the source location of the
|
||||
specific diagram element.
|
||||
the source location of the specific diagram element.
|
||||
|
||||
## Resolving include path and compiler flags issues
|
||||
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
|
||||
already as `argv[0]` in your `compile_commands.json`, you can simply invoke
|
||||
`clang-uml` as:
|
||||
already as first argument of each compile command in your
|
||||
`compile_commands.json`, you can simply invoke `clang-uml` as:
|
||||
|
||||
```bash
|
||||
clang-uml --query-driver .
|
||||
|
||||
@@ -41,10 +41,10 @@ Some filters accept either specified exact values, some support regular
|
||||
expressions while some except glob patterns.
|
||||
|
||||
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
|
||||
would have to be escaped in situations such as `mycontainer<char*>`, so for
|
||||
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
|
||||
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
|
||||
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.+'``` |
|
||||
| `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
|
||||
|
||||
Allows to include or exclude entities from specific namespaces.
|
||||
|
||||
```yaml
|
||||
include:
|
||||
namespaces:
|
||||
- ns1::ns2
|
||||
exclude:
|
||||
namespaces:
|
||||
- ns1::ns2::detail
|
||||
```
|
||||
|
||||
## elements
|
||||
|
||||
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:
|
||||
t00061_class:
|
||||
type: class
|
||||
relative_to: ../../tests/t00061
|
||||
glob: [t00061.cc]
|
||||
glob:
|
||||
- t00061.cc
|
||||
include:
|
||||
paths: [include/t00061_a.h]
|
||||
paths:
|
||||
- include/t00061_a.h
|
||||
using_namespace:
|
||||
- clanguml::t00061
|
||||
```
|
||||
@@ -166,14 +176,14 @@ include inheritance and template specialization/instantiation relationships add
|
||||
```
|
||||
|
||||
The following relationships can be used in this filter:
|
||||
* inheritance
|
||||
* composition
|
||||
* aggregation
|
||||
* ownership
|
||||
* association
|
||||
* instantiation
|
||||
* friendship
|
||||
* dependency
|
||||
* `inheritance`
|
||||
* `composition`
|
||||
* `aggregation`
|
||||
* `ownership`
|
||||
* `association`
|
||||
* `instantiation`
|
||||
* `friendship`
|
||||
* `dependency`
|
||||
|
||||
## subclasses
|
||||
|
||||
@@ -198,13 +208,13 @@ This filter allows to include or exclude class methods and members based on thei
|
||||
## method_types
|
||||
|
||||
This filter allows to include or exclude various method types from the class diagram, allowed values ar:
|
||||
* constructor
|
||||
* destructor
|
||||
* assignment
|
||||
* operator
|
||||
* defaulted
|
||||
* deleted
|
||||
* static
|
||||
* `constructor`
|
||||
* `destructor`
|
||||
* `assignment`
|
||||
* `operator`
|
||||
* `defaulted`
|
||||
* `deleted`
|
||||
* `static`
|
||||
|
||||
This filter is independent of the `access` filter, which controls which methods
|
||||
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.
|
||||
|
||||
The following callee types are supported:
|
||||
* constructor
|
||||
* assignment
|
||||
* operator
|
||||
* defaulted
|
||||
* static
|
||||
* method
|
||||
* function
|
||||
* function_template
|
||||
* lambda
|
||||
* `constructor`
|
||||
* `assignment`
|
||||
* `operator`
|
||||
* `defaulted`
|
||||
* `static`
|
||||
* `method`
|
||||
* `function`
|
||||
* `function_template`
|
||||
* `lambda`
|
||||
|
||||
## dependants and dependencies
|
||||
|
||||
|
||||
@@ -12,7 +12,7 @@ Currently, there are 3 types of diagram generators: `plantuml`, `mermaid`
|
||||
and `json`.
|
||||
|
||||
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
|
||||
clang-uml -g plantuml -g mermaid -g json
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 1.1 KiB After Width: | Height: | Size: 7.0 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 772 B After Width: | Height: | Size: 6.0 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 867 B After Width: | Height: | Size: 6.3 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 1.0 KiB After Width: | Height: | Size: 6.9 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 1.1 KiB After Width: | Height: | Size: 6.8 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 1.3 KiB After Width: | Height: | Size: 7.5 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 976 B After Width: | Height: | Size: 6.6 KiB |
@@ -6,17 +6,13 @@
|
||||
|
||||
<!-- tocstop -->
|
||||
|
||||
Include diagrams allow to document the include dependencies among different parts of the project. This can be very useful
|
||||
for instance to detect that a file was included from a module directory, on which specific part of the project
|
||||
should not ever depend.
|
||||
Include diagrams allow to document the include dependencies among different
|
||||
parts of the project. This can be very useful for instance to detect that a file
|
||||
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:
|
||||
```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:
|
||||
# Diagram name
|
||||
my_class_diagram:
|
||||
@@ -25,8 +21,6 @@ diagrams:
|
||||
# Include only translation units matching the following patterns
|
||||
glob:
|
||||
- src/*.cc
|
||||
# Render the paths relative to this directory
|
||||
relative_to: src
|
||||
# Include also external system headers
|
||||
generate_system_headers: true
|
||||
# Include only classes and functions from files in `src` directory
|
||||
@@ -36,29 +30,31 @@ diagrams:
|
||||
- src
|
||||
```
|
||||
|
||||
One distinctive option in `include` diagrams is `relative_to`, which tells `clang-uml` to render all filename
|
||||
paths relative to this directory.
|
||||
One distinctive option in `include` diagrams is `relative_to`, which tells
|
||||
`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 |
|
||||
| ---- | --- |
|
||||
| Include (local) |  |
|
||||
| Include (system) |  |
|
||||
| UML | PlantUML | MermaidJS |
|
||||
|-----------------------------------------|------------------------------------------|---------------------------------------------|
|
||||
| Include (local) |  |  |
|
||||
| Include (system) |  |  |
|
||||
|
||||
## 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
|
||||
the following option to the diagram:
|
||||
In case you would like to include the information about what system headers your
|
||||
project files include simply add the following option to the diagram:
|
||||
|
||||
```yaml
|
||||
generate_system_headers: true
|
||||
```
|
||||
|
||||
This will include only system headers directly included from the projects source files (matched by `glob`) and not
|
||||
their dependencies, for example:
|
||||
This will include only system headers directly included from the project's
|
||||
source files (matched by `glob`) and not their dependencies, for example:
|
||||
|
||||
|
||||
|
||||
Please note that generating include diagram, which contains third party and system library headers will result
|
||||
in a huge diagram that will be unlikely to be useful.
|
||||
Please note that generating include diagram, which contains third party and
|
||||
system library headers will result in a huge diagram that will be unlikely to
|
||||
be useful.
|
||||
@@ -64,8 +64,8 @@ Download and run the latest Windows installer from
|
||||
First make sure that you have the following dependencies installed:
|
||||
|
||||
```bash
|
||||
# Ubuntu (clang version will vary depending on Ubuntu version)
|
||||
apt install ccache cmake libyaml-cpp-dev clang-12 libclang-12-dev libclang-cpp12-dev
|
||||
# Ubuntu (Clang version will vary depending on Ubuntu version - below example is for Ubuntu 22.04)
|
||||
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:
|
||||
@@ -81,6 +81,9 @@ release/src/clang-uml --help
|
||||
LLVM_VERSION=16 make release
|
||||
# or specify path to a specific llvm-config binary, e.g.:
|
||||
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
|
||||
make install
|
||||
@@ -96,8 +99,10 @@ export PATH=$PATH:$PWD/release
|
||||
brew install ccache cmake llvm yaml-cpp
|
||||
|
||||
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
|
||||
# or, if this fails, try:
|
||||
CMAKE_PREFIX=/usr/local/opt/llvm/lib/cmake/llvm make release
|
||||
```
|
||||
|
||||
#### Windows
|
||||
|
||||
@@ -6,13 +6,13 @@
|
||||
|
||||
<!-- tocstop -->
|
||||
|
||||
`clang-uml` in combination with PlantUML's link generation in diagrams allows to
|
||||
generate interactive diagrams, where clicking on any class, method or call
|
||||
expression can direct the user directly to the source code or some other
|
||||
diagram or document available online.
|
||||
`clang-uml` in combination with PlantUML and MermaidJS link generation in
|
||||
diagrams allows to generate interactive diagrams, where clicking on any class,
|
||||
method or call expression can direct the user directly to the source code or
|
||||
some other diagram or document available online.
|
||||
|
||||
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
|
||||
generate_links:
|
||||
|
||||
@@ -7,16 +7,11 @@
|
||||
<!-- tocstop -->
|
||||
|
||||
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.
|
||||
|
||||
The minimal config required to generate a package diagram is presented below:
|
||||
```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:
|
||||
# Diagram name
|
||||
my_class_diagram:
|
||||
|
||||
@@ -8,7 +8,7 @@
|
||||
|
||||
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
|
||||
clang-uml --init
|
||||
```
|
||||
@@ -36,10 +36,10 @@ To add an initial class diagram to your project, follow these steps:
|
||||
namespaces:
|
||||
- myproject::detail
|
||||
```
|
||||
3. Run `clang-uml` in the projects top directory:
|
||||
3. Run `clang-uml` in the project's top directory:
|
||||
```bash
|
||||
clang-uml
|
||||
# or to see generation progress for each diagram run
|
||||
# or to see generation progress for each diagram
|
||||
clang-uml --progress
|
||||
```
|
||||
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
|
||||
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
|
||||
clang-uml -l
|
||||
The following diagrams are defined in the config file:
|
||||
|
||||
@@ -55,23 +55,23 @@ C++ code, the following assumptions were made:
|
||||
from plain old C code). Functions can also be aggregated into file
|
||||
participants, based on their place of declaration
|
||||
* Call expressions in conditional expressions in block statements (e.g. `if`
|
||||
or `while`) are rendered inside the PlantUML `alt` or `loop` blocks but
|
||||
wrapped in `[`, `]` brackets
|
||||
or `while`) are rendered inside the PlantUML or MermaidJS `alt` or `loop`
|
||||
blocks but wrapped in `[`, `]` brackets
|
||||
* Lambda expressions are generated as standalone participants, whose name
|
||||
comprises the parent context where they are defined and the exact source code
|
||||
location
|
||||
|
||||
## 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,
|
||||
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
|
||||
`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
|
||||
* `from_to` - will include all call chains which start and end at the specified
|
||||
location constraints
|
||||
* `from_to` - will include all call chains, which start and end at the specified
|
||||
locations
|
||||
|
||||
Currently, the constraints can be a method or a free function, both specified
|
||||
using the full signature of the function, e.g.
|
||||
@@ -97,7 +97,7 @@ and `to` locations as follows:
|
||||
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:
|
||||
|
||||
```bash
|
||||
@@ -255,18 +255,16 @@ results in the following diagram:
|
||||
## Customizing participants order
|
||||
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
|
||||
depending on the specific call chain in the code. It is however
|
||||
possible to override this order in the diagram definition using
|
||||
`participants_order` property, for instance like this test case:
|
||||
depending on the specific call chain in the code. It is however possible to
|
||||
override this order in the diagram definition using `participants_order`
|
||||
property, for instance like this test case:
|
||||
|
||||
```yaml
|
||||
compilation_database_dir: ..
|
||||
output_directory: diagrams
|
||||
diagrams:
|
||||
t20029_sequence:
|
||||
type: sequence
|
||||
glob:
|
||||
- ../../tests/t20029/t20029.cc
|
||||
- t20029.cc
|
||||
include:
|
||||
namespaces:
|
||||
- clanguml::t20029
|
||||
@@ -296,13 +294,12 @@ following configuration option:
|
||||
generate_return_types: true
|
||||
```
|
||||
|
||||
This option only affects the `plantuml` generation, in `json` generator
|
||||
`return_type` property is always present in the message nodes.
|
||||
This option only affects the `plantuml` and `mermaid` generators, in `json`
|
||||
generator `return_type` property is always present in the message nodes.
|
||||
|
||||
The diagram below presents what it looks like in a PlantUML generated diagram:
|
||||
|
||||
|
||||
|
||||
## Generating condition statements
|
||||
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
|
||||
@@ -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.
|
||||
|
||||
However, a call expression can be injected manually through a comment
|
||||
directive `\uml{note CALLEE}`, when placed just before such line of code, for
|
||||
example:
|
||||
directive
|
||||
```cpp
|
||||
// \uml{note CALLEE}
|
||||
```
|
||||
|
||||
It should be placed in the comment just before such line of code, for example:
|
||||
|
||||
```cpp
|
||||
// \uml{call clanguml::t20038::B::bbb()}
|
||||
@@ -346,7 +347,7 @@ add_compile_flags:
|
||||
otherwise Clang will skip these comments during AST traversal.
|
||||
|
||||
## 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
|
||||
[t20038](test_cases/t20038_sequence.svg)).
|
||||
|
||||
|
||||
@@ -9,7 +9,7 @@
|
||||
* [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)
|
||||
* [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)
|
||||
* ["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)
|
||||
@@ -27,7 +27,7 @@
|
||||
If `clang-uml` crashes with a segmentation fault, it is possible to trace the
|
||||
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
|
||||
make debug
|
||||
@@ -35,15 +35,16 @@ make debug
|
||||
|
||||
Then run `clang-uml`, preferably with `-vvv` for verbose log output. If your
|
||||
`.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
|
||||
debug/src/clang-uml -vvv -n my_diagram
|
||||
```
|
||||
|
||||
After `clang-uml` crashes again, detailed backtrace (generated using
|
||||
[backward-cpp](https://github.com/bombela/backward-cpp)) should be visible
|
||||
on the console.
|
||||
[backward-cpp](https://github.com/bombela/backward-cpp) library) should be
|
||||
visible on the console.
|
||||
|
||||
If possible, [create an issue](https://github.com/bkryza/clang-uml/issues) and
|
||||
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's [RecursiveASTVisitor](https://clang.llvm.org/doxygen/classclang_1_1RecursiveASTVisitor.html),
|
||||
to
|
||||
traverse the source code. By default, this visitor is invoked on every
|
||||
to traverse the source code. By default, this visitor is invoked on every
|
||||
translation unit (i.e. each entry in your `compile_commands.json`), including
|
||||
all of their header dependencies recursively. This means, that for large code
|
||||
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 -
|
||||
```
|
||||
|
||||
## 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
|
||||
schema validation, and exits if the configuration file is invalid.
|
||||
|
||||
@@ -325,11 +325,10 @@ Hopefully this will be eventually resolved.
|
||||
|
||||
### Generated diagram is empty
|
||||
|
||||
In order to generate sequence diagram the `start_from` configuration option must
|
||||
have a valid starting point
|
||||
In order to generate sequence diagram the location constraints (`from`, `to`
|
||||
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
|
||||
or method signature in the `clang-uml` diagram model.
|
||||
|
||||
Look for error in the console output such as:
|
||||
|
||||
```bash
|
||||
@@ -341,16 +340,19 @@ configuration file, or that the function
|
||||
was not defined in the translation units you specified in the `glob` patterns
|
||||
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:
|
||||
|
||||
```bash
|
||||
clang-uml -n my_sequence_diagram --print-start-from | grep foo
|
||||
```
|
||||
|
||||
Command line flag `--print-start-from` will print on stdout all functions
|
||||
and methods available in the diagram model, and each line of this output
|
||||
can be directly used as a value of `start_from` option in the config file.
|
||||
|
||||
Command line flag `--print-from` will print on stdout all functions
|
||||
and methods available in the diagram model which can be used as starting
|
||||
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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user