diff --git a/CHANGELOG.md b/CHANGELOG.md index 7bcc9d88..fc27819d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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) diff --git a/README.md b/README.md index 40d85354..a0aa5e89 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/docs/architecture.md b/docs/architecture.md index 2367eb42..9f519101 100644 --- a/docs/architecture.md +++ b/docs/architecture.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.: diff --git a/docs/class_diagrams.md b/docs/class_diagrams.md index 26240c4f..a652f2dd 100644 --- a/docs/class_diagrams.md +++ b/docs/class_diagrams.md @@ -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 | ![extension](img/puml_inheritance.png) | -| Association | ![association](img/puml_association.png) | -| Dependency | ![dependency](img/puml_dependency.png) | -| Aggregation | ![aggregation](img/puml_aggregation.png) | -| Composition | ![composition](img/puml_composition.png) | -| Template specialization/instantiation | ![specialization](img/puml_instantiation.png) | -| Nesting (inner class/enum) | ![nesting](img/puml_nested.png) | +| UML | PlantUML | MermaidJS | +| ---- | --- |--------------------------------------------| +| Inheritance | ![extension](img/puml_inheritance.png) | ![extension](img/mermaid_inheritance.png) | +| Association | ![association](img/puml_association.png) | ![extension](img/mermaid_association.png) | +| Dependency | ![dependency](img/puml_dependency.png) | ![extension](img/mermaid_dependency.png) | +| Aggregation | ![aggregation](img/puml_aggregation.png) | ![extension](img/mermaid_aggregation.png) | +| Composition | ![composition](img/puml_composition.png) | ![extension](img/mermaid_composition.png) | +| Template specialization/instantiation | ![specialization](img/puml_instantiation.png) | ![extension](img/mermaid_instantiation.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 @@ -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: ![t00036_class](test_cases/t00036_class.svg) -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: diff --git a/docs/common_options.md b/docs/common_options.md index f1483374..38513e05 100644 --- a/docs/common_options.md +++ b/docs/common_options.md @@ -15,8 +15,8 @@ ## 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 . diff --git a/docs/diagram_filters.md b/docs/diagram_filters.md index 01c94f5a..3bfd9f38 100644 --- a/docs/diagram_filters.md +++ b/docs/diagram_filters.md @@ -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`, 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```, 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 diff --git a/docs/generator_types.md b/docs/generator_types.md index c364fbd5..214e7554 100644 --- a/docs/generator_types.md +++ b/docs/generator_types.md @@ -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 diff --git a/docs/img/mermaid_aggregation.png b/docs/img/mermaid_aggregation.png index 10a052b7..04d9b0fb 100644 Binary files a/docs/img/mermaid_aggregation.png and b/docs/img/mermaid_aggregation.png differ diff --git a/docs/img/mermaid_association.png b/docs/img/mermaid_association.png index 005737e6..91819408 100644 Binary files a/docs/img/mermaid_association.png and b/docs/img/mermaid_association.png differ diff --git a/docs/img/mermaid_composition.png b/docs/img/mermaid_composition.png index 3562b65a..c21bc1ee 100644 Binary files a/docs/img/mermaid_composition.png and b/docs/img/mermaid_composition.png differ diff --git a/docs/img/mermaid_dependency.png b/docs/img/mermaid_dependency.png index f4cb8a9c..fab032ef 100644 Binary files a/docs/img/mermaid_dependency.png and b/docs/img/mermaid_dependency.png differ diff --git a/docs/img/mermaid_inheritance.png b/docs/img/mermaid_inheritance.png index 01b75c5f..ce34ce04 100644 Binary files a/docs/img/mermaid_inheritance.png and b/docs/img/mermaid_inheritance.png differ diff --git a/docs/img/mermaid_instantiation.png b/docs/img/mermaid_instantiation.png index cde3a265..49ecf289 100644 Binary files a/docs/img/mermaid_instantiation.png and b/docs/img/mermaid_instantiation.png differ diff --git a/docs/img/mermaid_nested.png b/docs/img/mermaid_nested.png index 144c5c4f..ae0725c6 100644 Binary files a/docs/img/mermaid_nested.png and b/docs/img/mermaid_nested.png differ diff --git a/docs/include_diagrams.md b/docs/include_diagrams.md index 0a2041e0..401a0ede 100644 --- a/docs/include_diagrams.md +++ b/docs/include_diagrams.md @@ -6,17 +6,13 @@ -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) | ![association](img/puml_association.png) | -| Include (system) | ![dependency](img/puml_dependency.png) | +| UML | PlantUML | MermaidJS | +|-----------------------------------------|------------------------------------------|---------------------------------------------| +| Include (local) | ![association](img/puml_association.png) | ![association](img/mermaid_association.png) | +| Include (system) | ![dependency](img/puml_dependency.png) | ![association](img/mermaid_dependency.png) | ## 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: ![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 be useful. \ No newline at end of file +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. \ No newline at end of file diff --git a/docs/installation.md b/docs/installation.md index 5a8b71bf..e1af79e8 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -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 diff --git a/docs/interactive_svg_diagrams.md b/docs/interactive_svg_diagrams.md index aadb6375..3358057e 100644 --- a/docs/interactive_svg_diagrams.md +++ b/docs/interactive_svg_diagrams.md @@ -6,13 +6,13 @@ -`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: diff --git a/docs/package_diagrams.md b/docs/package_diagrams.md index 756e3b72..5e542be2 100644 --- a/docs/package_diagrams.md +++ b/docs/package_diagrams.md @@ -7,16 +7,11 @@ 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: diff --git a/docs/quick_start.md b/docs/quick_start.md index d696c2f0..3ff1bad1 100644 --- a/docs/quick_start.md +++ b/docs/quick_start.md @@ -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: diff --git a/docs/sequence_diagrams.md b/docs/sequence_diagrams.md index 60b150c6..fea46abb 100644 --- a/docs/sequence_diagrams.md +++ b/docs/sequence_diagrams.md @@ -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: ![extension](test_cases/t20032_sequence.svg) - ## 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)). diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 49705bac..d708e181 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -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