From 812979779be65cc3c41847759ea270e0a1b729ac Mon Sep 17 00:00:00 2001 From: Bartek Kryza Date: Tue, 5 Mar 2024 17:36:48 +0100 Subject: [PATCH] Fixed issues in docs --- docs/class_diagrams.md | 12 ++++++--- docs/common_options.md | 55 +++++++++++++++++++++++---------------- docs/diagram_filters.md | 6 ++--- docs/generator_types.md | 20 +++++++++++--- docs/include_diagrams.md | 2 +- docs/installation.md | 18 ++++++------- docs/package_diagrams.md | 12 +++++---- docs/quick_start.md | 4 +-- docs/sequence_diagrams.md | 14 +++++----- docs/troubleshooting.md | 4 +-- 10 files changed, 87 insertions(+), 60 deletions(-) diff --git a/docs/class_diagrams.md b/docs/class_diagrams.md index ac6a670b..dda12be7 100644 --- a/docs/class_diagrams.md +++ b/docs/class_diagrams.md @@ -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: diff --git a/docs/common_options.md b/docs/common_options.md index 38513e05..c8fea3ba 100644 --- a/docs/common_options.md +++ b/docs/common_options.md @@ -15,30 +15,34 @@ ## 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: diff --git a/docs/diagram_filters.md b/docs/diagram_filters.md index 759b7c49..4e996f4f 100644 --- a/docs/diagram_filters.md +++ b/docs/diagram_filters.md @@ -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.+'``` | diff --git a/docs/generator_types.md b/docs/generator_types.md index 214e7554..75877fa6 100644 --- a/docs/generator_types.md +++ b/docs/generator_types.md @@ -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 diff --git a/docs/include_diagrams.md b/docs/include_diagrams.md index 401a0ede..fd3572b9 100644 --- a/docs/include_diagrams.md +++ b/docs/include_diagrams.md @@ -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. \ No newline at end of file diff --git a/docs/installation.md b/docs/installation.md index e3b16b87..7f350f9d 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -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: diff --git a/docs/package_diagrams.md b/docs/package_diagrams.md index 952436c6..ef483e92 100644 --- a/docs/package_diagrams.md +++ b/docs/package_diagrams.md @@ -7,8 +7,8 @@ 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: diff --git a/docs/quick_start.md b/docs/quick_start.md index 3ff1bad1..0f208632 100644 --- a/docs/quick_start.md +++ b/docs/quick_start.md @@ -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. diff --git a/docs/sequence_diagrams.md b/docs/sequence_diagrams.md index fea46abb..a75a4619 100644 --- a/docs/sequence_diagrams.md +++ b/docs/sequence_diagrams.md @@ -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). diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index d708e181..23fe0a1d 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -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