From 0fd0d9778672830bbea351cd74da09a5b5ebe4cb Mon Sep 17 00:00:00 2001 From: Bartek Kryza Date: Wed, 5 Jul 2023 22:39:19 +0200 Subject: [PATCH] Updated docs --- docs/sequence_diagrams.md | 26 ++++++++++++-------------- docs/troubleshooting.md | 20 ++++++++++++++------ 2 files changed, 26 insertions(+), 20 deletions(-) diff --git a/docs/sequence_diagrams.md b/docs/sequence_diagrams.md index 7cc2872b..8b111501 100644 --- a/docs/sequence_diagrams.md +++ b/docs/sequence_diagrams.md @@ -61,7 +61,7 @@ diagram should start. Currently, the entry point can only be a method or a free configuration property, for instance: ```yaml start_from: - - function: "main(int,char**)" + - function: "main(int,const char**)" ``` or ```yaml @@ -69,23 +69,21 @@ start_from: - function: "clanguml::sequence_diagram::visitor::translation_unit_visitor::VisitCXXRecordDecl(clang::CXXRecordDecl *)" ``` -The entrypoints must be fully qualified and they must match exactly the string representation of given function or -method in the `clang-uml` model, which can be frustrating after few attempts. -If not sure, the best way is to put anything in the `function` -property value at first, run the `clang-uml` on the diagram with verbose set to `-vvv` and look in the logs -for the relevant function signature. At the end of the diagram generation at this verbosity level, `clang-uml` will -generate a textual representation of all discovered activities relevant for this diagram, for instance if you're looking -_for exact signature of method `translation_unit_visitor::VisitCXXRecordDecl`, look for similar_ -output in the logs: +The entrypoints must be fully qualified and they must match exactly the string +representation of given function or method in the `clang-uml` model. + +To find the exact function signature run `clang-uml` as follows: ```bash -[trace] [tid 3842954] [diagram.cc:194] Sequence id=1875210076312968845: -[trace] [tid 3842954] [diagram.cc:198] Activity id=1875210076312968845, from=clanguml::sequence_diagram::visitor::translation_unit_visitor::VisitCXXRecordDecl(clang::CXXRecordDecl *): -[trace] [tid 3842954] [diagram.cc:208] Message from=clanguml::sequence_diagram::visitor::translation_unit_visitor::VisitCXXRecordDecl(clang::CXXRecordDecl *), from_id=1875210076312968845, to=__UNRESOLVABLE_ID__, to_id=0, name=, type=if -[trace] [tid 3842954] [diagram.cc:217] Message from=clanguml::sequence_diagram::visitor::translation_unit_visitor::VisitCXXRecordDecl(clang::CXXRecordDecl *), from_id=1875210076312968845, to=clanguml::sequence_diagram::visitor::translation_unit_visitor::should_include(const clang::TagDecl *), to_id=664596622746486441, name=should_include, type=call +clang-uml --print-start-from -n main_sequence | grep main ``` -Then you just need to copy and paste the signature exactly and rerun `clang-uml`. +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. + +Since that list can be quite large, it's best to filter the output to limit +the number of lines to a subset of possible candidates. ## Grouping free functions by file By default, `clang-uml` will generate a new participant for each call to a free function (not method), which can lead diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 60c43f83..997e3b2e 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -320,7 +320,8 @@ Hopefully this will be eventually resolved. In order to generate sequence diagram the `start_from` configuration option must have a valid starting point for the diagram (e.g. `function`), which must match exactly the function -signature in the `clang-uml` model. +or method signature in the `clang-uml` diagram model. + Look for error in the console output such as: ```bash @@ -330,11 +331,18 @@ Failed to find participant mynamespace::foo(int) for start_from condition which means that either you have a typo in the function signature in the configuration file, or that the function was not defined in the translation units you specified in the `glob` patterns -for this diagram. Run again the -`clang-uml` tool with `-vvv` option and look in the console output for any -mentions of the function from -which the diagram should start and copy the exact signature into the -configuration file. +for this diagram. + +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. + ### Generated diagram contains several empty control blocks or calls which should not be there