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

Fixed issues in docs

Browse Source
This commit is contained in:
Bartek Kryza
2024-03-05 17:36:48 +01:00
parent ba9e435786
commit 812979779b
10 changed files with 87 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/class_diagrams.md
View File

@@ -90,8 +90,10 @@ type of relationship generated in the class diagrams.
By default, a member from which a relationship has been added to the diagram
between 2 classes will also be rendered inside the class. This behaviour can be
however disabled by adding the following option to the diagram definition:
between 2 classes will also be rendered inside as a property inside the class
box. This behaviour can be however disabled by adding the following option to
the diagram definition:
```yaml
include_relations_also_as_members: false
```
@@ -158,7 +160,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
In case the code base is structured based on subdirectories 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:
@@ -175,8 +177,10 @@ 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:
@@ -213,7 +217,7 @@ this can be easily achieved using `context` inclusion filter:
```
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
`ns1::MyClass`, but an additional 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:

55
docs/common_options.md
View File

@@ -15,30 +15,34 @@
<!-- tocstop -->
## Overall configuration file structure
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:
By default, `clang-uml` will look for file `.clang-uml` in the project's
directory and read all diagram 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
...
# Common options for all diagrams
# ...
# Diagram definitions
diagrams:
first_diagram_name:
type: class|sequence|package|include
# diagram specific options
...
# Diagram specific options
# ...
second_diagram_name:
type: class|sequence|package|include
# diagram specific options
...
...
# Diagram specific options
# ...
# More diagrams
# ...
```
The top level common options are inherited by specific diagrams, if the option is applicable to them and they themselves
do not override this option.
The top level common options are inherited by specific diagrams, if the option
is applicable to them and they themselves do not override this option.
For detailed reference of all configuration options see [here](./configuration_file.md).
Effective configuration, including default values can be printed out in YAML format using the following option:
Effective configuration, including default values can be printed out in YAML
format using the following option:
```bash
clang-uml --dump-config
@@ -56,10 +60,11 @@ diagrams:
```
## Translation unit glob patterns
One of the key options of the diagram configuration is the list of translation units, which should be parsed to
get all necessary information for a diagram.
One of the key options of the diagram configuration is the list of translation
units, which should be parsed to get all necessary information for a diagram.
The syntax is simple and based on glob patterns, which can be added to the configuration file as follows:
The syntax is simple and based on glob patterns, which can be added to the
configuration file as follows:
```yaml
glob:
@@ -67,13 +72,17 @@ The syntax is simple and based on glob patterns, which can be added to the confi
- src/dir3/*.cc
```
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`
pattern set does not match any translation units an error will be printed on the standard output.
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`
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
for each diagram to absolute minimum will significantly decrease the diagram generation times.
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 for each diagram to minimum necessary to discover all necessary diagram
elements will significantly decrease the diagram generation times.
## Custom directives
In case it's necessary to add some custom PlantUML or MermaidJS declarations
@@ -122,13 +131,13 @@ the generated PlantUML diagram will contain comments before each line containing
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
Due to the fact, that a project can be compiled with different compilers
and toolchains, the system paths and compilation flags detected by the Clang
version linked to your `clang-uml` installation might differ from the ones
actually used to compile your project.
> This is often an issue on macOS, when `clang-uml` uses Homebrew version of LLVM
> and your project was built using system Apple Clang
> and a project was built using system Apple Clang.
Typically, this results in error messages on the console during diagram
generation, such as:

6
docs/diagram_filters.md
View File

@@ -40,7 +40,7 @@ to your diagram configuration:
```
Some filters accept either specified exact values, some support regular
expressions while some except glob patterns.
expressions while some accept 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
@@ -54,8 +54,6 @@ exclude:
- r: '.*test.*'
```
`paths` filter is currently the only filter which accepts `glob` like patterns.
The following table specifies the values allowed in each filter:
| Filter name | Possible values | Example values |
@@ -64,7 +62,7 @@ The following table specifies the values allowed in each filter:
| `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``` |
| `paths` | File or dir path | ```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.+'``` |

20
docs/generator_types.md
View File

@@ -51,6 +51,20 @@ instance:
cmd: "/usr/bin/plantuml -tsvg \"diagrams/{}.puml\""
```
Furthermore, `plantuml` generator accepts basic styling options for customizing
diagram look and layout, e.g.:
```yaml
plantuml:
style:
# Apply this style to all classes in the diagram
class: "#aliceblue;line:blue;line.dotted;text:blue"
# Apply this style to all packages in the diagram
package: "#back:grey"
# Make all template instantiation relations point upwards and draw them
# as green and dotted lines
instantiation: "up[#green,dotted]"
```
An example PlantUML diagram is presented below:
```plantuml
@@ -121,9 +135,9 @@ example:
- 'note for {{ alias("config") }} "General options not used by diagrams."'
```
will add before the diagram contents (right after diagram type,
e.g. `classDiagram`) diagram direction hint, and after each diagram contents
2 notes attached to elements.
will add a diagram direction hint before the diagram contents (right after
diagram type, e.g. `classDiagram`), and after each diagram contents
2 notes attached to classes `inheritable_diagram_options` and `config`.
This generator also accepts a `cmd` parameter to specify a command to execute
on the generated MermaidJS source file to generate actual diagram image, for

2
docs/include_diagrams.md
View File

@@ -56,5 +56,5 @@ source files (matched by `glob`) and not their dependencies, for example:
![t40001_include](./test_cases/t40001_include.svg)
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
system library headers will result in a huge diagram that is unlikely to
be useful.

18
docs/installation.md
View File

@@ -23,7 +23,7 @@
#### Ubuntu
```bash
# Currently supported Ubuntu versions are Focal, Jammy, Lunar and Mantic
# Currently supported Ubuntu versions are Focal, Jammy and Mantic
sudo add-apt-repository ppa:bkryza/clang-uml
sudo apt update
sudo apt install clang-uml
@@ -33,16 +33,16 @@ sudo apt install clang-uml
```bash
# Fedora 37
wget https://github.com/bkryza/clang-uml/releases/download/0.4.2/clang-uml-0.4.2-1.fc37.x86_64.rpm
sudo dnf install ./clang-uml-0.4.2-1.fc37.x86_64.rpm
wget https://github.com/bkryza/clang-uml/releases/download/0.5.1/clang-uml-0.5.1-1.fc37.x86_64.rpm
sudo dnf install ./clang-uml-0.5.1-1.fc37.x86_64.rpm
# Fedora 38
wget https://github.com/bkryza/clang-uml/releases/download/0.4.2/clang-uml-0.4.2-1.fc38.x86_64.rpm
sudo dnf install ./clang-uml-0.4.2-1.fc38.x86_64.rpm
wget https://github.com/bkryza/clang-uml/releases/download/0.5.1/clang-uml-0.5.1-1.fc38.x86_64.rpm
sudo dnf install ./clang-uml-0.5.1-1.fc38.x86_64.rpm
# Fedora 39
wget https://github.com/bkryza/clang-uml/releases/download/0.4.2/clang-uml-0.4.2-1.fc39.x86_64.rpm
sudo dnf install ./clang-uml-0.4.2-1.fc39.x86_64.rpm
wget https://github.com/bkryza/clang-uml/releases/download/0.5.1/clang-uml-0.5.1-1.fc39.x86_64.rpm
sudo dnf install ./clang-uml-0.5.1-1.fc39.x86_64.rpm
```
#### Conda
@@ -79,7 +79,7 @@ release/src/clang-uml --help
# To build using a specific installed version of LLVM use:
LLVM_VERSION=16 make release
# or specify path to a specific llvm-config binary, e.g.:
# or specify a 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
@@ -111,7 +111,7 @@ CMAKE_PREFIX=/usr/local/opt/llvm/lib/cmake/llvm make release
##### Visual Studio native build
These steps present how to build and use `clang-uml` natively using Visual Studio only.
These steps present how to build and use `clang-uml` natively using Microsoft Visual Studio only.
First, install the following dependencies manually:

12
docs/package_diagrams.md
View File

@@ -7,8 +7,8 @@
<!-- tocstop -->
Package diagrams are simple diagrams, which can be useful to visualize a high
level structure of a C++ project, by rendering project's namespaces or
subdirectories as UML packages and their interdependencies.
level structure of a C++ project, by rendering project's namespaces,
subdirectories or modules as UML packages and their interdependencies.
The minimal config required to generate a package diagram is presented below:
```yaml
@@ -163,7 +163,8 @@ the configuration file:
package_type: directory
```
for example check out this diagram
for example check out this diagram (you can click on package names to see the
corresponding source directory):
![t30011_package](./test_cases/t30011_package.svg)
Module based packages can be enabled using the following option:
@@ -172,8 +173,9 @@ Module based packages can be enabled using the following option:
package_type: module
```
for example check out this diagram
![t30014_package](./test_cases/t30011_package.svg)
for example check out this diagram (you can click on package names to see the
corresponding module source):
![t30014_package](./test_cases/t30012_package.svg)
Diagrams can be rendered relative to a specific module using `using_module`
option:

4
docs/quick_start.md
View File

@@ -52,9 +52,9 @@ To add an initial class diagram to your project, follow these steps:
mmdc -i diagrams/some_class_diagram.mmd -o diagrams/some_class_diagram.svg
```
Steps 3 and 4 can be combined into one step like follows:
Steps 3 and 4 can be combined into one step:
```
clang-uml -p -n some_class_diagram -g plantuml -r --plantuml-cmd="plantuml -tsvg diagrams/{}.puml"
clang-uml -p -n some_class_diagram -g plantuml -r --plantuml-cmd="/usr/bin/plantuml -tsvg diagrams/{}.puml"
```
where `-r` enables diagram rendering and `--plantuml-cmd` specifies command
to execute on each generated diagram.

14
docs/sequence_diagrams.md
View File

@@ -74,7 +74,7 @@ there are 3 types of constraints:
locations
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.:
```yaml
from:
@@ -97,8 +97,8 @@ and `to` locations as follows:
function: "clanguml::t20034::A::a2()"]
```
To find the exact function signature which, can be used as a `from` location,
run `clang-uml` as follows:
To find the exact function signature, which can be used as a `from` location,
run `clang-uml` as follows (assuming the function of interest is called `main`):
```bash
clang-uml --print-from -n main_sequence | grep main
@@ -112,7 +112,7 @@ clang-uml --print-to -n main_sequence | grep main
Command line flags `--print-from` and `--print-to` 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`, `from_to` or `to`
output can be directly used as a value of `from`, `from_to` or `to`
properties in the config file.
Since that list can be quite large, it's best to filter the output to limit
@@ -141,7 +141,7 @@ tentative support, which follows the following rules:
* If lambda expression is passed to some function or method, which is outside
the scope of the diagram (e.g. used in `std::transform` call) the call will
not be generated
* If the lambda is passed as template parameter in instantiation it will not
* If the lambda is passed as template argument in instantiation it will not
be generated
Another issue is the naming of lambda participants. Currently, each lambda is
@@ -257,7 +257,7 @@ 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:
property, for instance like this:
```yaml
diagrams:
@@ -372,5 +372,5 @@ for each sequence diagram, which should include these comments.
In case only selected messages should have some specific comments, instead
of enabling the `generate_message_comments` option, it is possible to use
`\uml{note TEXT}` directive in the comment above the expression, see
`\\uml{note TEXT}` directive in the comment above the expression, see
[t20001](test_cases/t20001_sequence.svg).

4
docs/troubleshooting.md
View File

@@ -22,7 +22,7 @@
## General issues
### clang-uml crashes when generating diagram
### clang-uml crashes when generating a diagram
If `clang-uml` crashes with a segmentation fault, it is possible to trace the
exact stack trace of the fault using the following steps:
@@ -346,7 +346,7 @@ 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
clang-uml -n my_sequence_diagram --print-from | grep foo
```
Command line flag `--print-from` will print on stdout all functions