Improved docs (#208)

Author: bkryza

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)

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)

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.:

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:

docs/common_options.md

@@ -15,8 +15,8 @@
 <!-- tocstop -->
 
 ## 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 .

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<char*>`, 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<char*>```, 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
 

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