From d140c1f1a11155369b8aa2951343b8a68dfcd4fb Mon Sep 17 00:00:00 2001 From: Bartek Kryza Date: Mon, 2 Jan 2023 21:00:40 +0100 Subject: [PATCH] Fixed documentation typos --- docs/class_diagrams.md | 10 ++++------ docs/comment_decorators.md | 2 +- docs/include_diagrams.md | 7 +++++++ docs/sequence_diagrams.md | 13 +++++++------ 4 files changed, 19 insertions(+), 13 deletions(-) diff --git a/docs/class_diagrams.md b/docs/class_diagrams.md index 1a49fcd2..23b53f74 100644 --- a/docs/class_diagrams.md +++ b/docs/class_diagrams.md @@ -29,7 +29,7 @@ The basic class diagram generated by `clang-uml` and rendered using PlantUML loo ![extension](test_cases/t00003_class.svg) -Parameter types and method return types are rendered at the end after `:` sign. +Member types and method return types are rendered at the end after `:` sign. Static methods and members are underlined. @@ -67,8 +67,6 @@ The following table presents the PlantUML arrows representing each relationship | Composition | ![composition](img/puml_composition.png) | | Template specialization/instantiation | ![specialization](img/puml_instantiation.png) | | Nesting (inner class/enum) | ![nesting](img/puml_nested.png) | -| Include (local) | ![association](img/puml_association.png) | -| Include (system) | ![dependency](img/puml_dependency.png) | By default, a member from which a relationship has been added to the diagram between 2 classes will also be rendered @@ -80,7 +78,7 @@ include_relations_also_as_members: false ### Relationships to classes in containers or smart pointers `clang-uml` will automatically detect class members as well as method arguments, which reference or own -values of types relevant for a given diagram but wrapped in smart pointers or containers ang still generate +values of types relevant for a given diagram but wrapped in smart pointers or containers and still generate relationship between these classes, for instance the following code: ```cpp @@ -130,7 +128,7 @@ which results in the following diagram: ## Class context diagram Sometimes it's helpful to generate a class diagram depicting only direct relationships of a given class, e.g. -within the classes documentation page, this can be easily achieved using `context` inclusion filter: +within the classes' documentation page, this can be easily achieved using `context` inclusion filter: ```yaml include: @@ -144,7 +142,7 @@ diagram: ![extension](test_cases/t00019_class.svg) -where the dependency relationships do not bring much information into the diagram. Thus in such cases it might +where the dependency relationships do not bring much information into the diagram. In such cases it might be useful to disable dependency relationships for this diagram completely using the following exclusion filter: ```yaml exclude: diff --git a/docs/comment_decorators.md b/docs/comment_decorators.md index 3492c2bf..1216bfa6 100644 --- a/docs/comment_decorators.md +++ b/docs/comment_decorators.md @@ -16,7 +16,7 @@ or The optional `:` suffix will apply this decorator only to a specific diagram. -Currently the following decorators are supported. +Currently, the following decorators are supported. ## `note` diff --git a/docs/include_diagrams.md b/docs/include_diagrams.md index 28daf7cc..7e92eda9 100644 --- a/docs/include_diagrams.md +++ b/docs/include_diagrams.md @@ -33,6 +33,13 @@ diagrams: 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. + +| UML | PlantUML | +| ---- | --- | +| Include (local) | ![association](img/puml_association.png) | +| Include (system) | ![dependency](img/puml_dependency.png) | + ## Tracking system headers directly included by projects files In case you would like to include the information about what system headers your projects file include simply add diff --git a/docs/sequence_diagrams.md b/docs/sequence_diagrams.md index bc8ffd1d..46070fde 100644 --- a/docs/sequence_diagrams.md +++ b/docs/sequence_diagrams.md @@ -33,19 +33,19 @@ Consider the following diagram: ![extension](test_cases/t20029_sequence.svg) -`clang-uml` generated sequence diagrams are not stricly speaking conforming to the UML specification, in order to +`clang-uml` generated sequence diagrams are not strictly speaking conforming to the UML specification. In order to make them more useful for documenting modern C++ code, the following assumptions were made: * Free functions are included in the sequence diagrams as standalone participants (in fact `clang-uml` can be used to generate sequence diagrams 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 - UML `alt` or `loop` blocks but wrapped in `[`, `]` brackets - * Lambda expressions are generated as standalone participants, whose name comprises of the parent context where they + PlantUML `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 entry point Sequence diagrams require an entry point for the diagram in order to determine, at which point in the code the sequence -diagram should start. Currently the entry point can only be a method or a free function, both specified using `start_from` +diagram should start. Currently, the entry point can only be a method or a free function, both specified using `start_from` configuration property, for instance: ```yaml start_from: @@ -58,7 +58,8 @@ start_from: ``` 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 tricky. If not sure, the best way is to put anything in the `function` +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 @@ -97,7 +98,7 @@ following rules: Another issue is the naming of lambda participants. Currently, each lambda is rendered in the diagram as a separate class whose name is composed of the lambda location in the code (the only unique way of identifying lambdas I was able -to find). For example the follwing code: +to find). For example the following code: ```cpp #include #include