Added Doxygen documentation

.clang-uml

@@ -2,10 +2,12 @@ compilation_database_dir: debug
 output_directory: docs/diagrams
 comment_parser: clang
 generate_links:
-  link: https://github.com/bkryza/clang-uml/blob/{{ git.commit }}/{{ element.source.path }}#L{{ element.source.line }}
+  link: "{% if existsIn(element, \"doxygen_link\") %}{{ element.doxygen_link }}{% endif %}"
   tooltip: "{% if existsIn(element, \"comment\") and existsIn(element.comment, \"brief\") %}{{ abbrv(trim(replace(element.comment.brief.0, \"\\n+\", \" \")), 256) }}{% else %}{{ element.name }}{% endif %}"
 diagrams:
   # Class diagrams
+  architecture_visitors_class:
+    include!: uml/class/architecture_visitors_class.yml
   config_class:
     include!: uml/class/config_class.yml
   config_context_class:
@@ -52,7 +54,7 @@ diagrams:
     include!: uml/class/sequence_model_class.yml
   package_model_class:
     include!: uml/class/package_model_class.yml
-  # Sequence diargams
+  # Sequence diagrams
   main_sequence:
     include!: uml/sequence/main_sequence.yml
   load_config_sequence:
@@ -70,6 +72,8 @@ diagrams:
   # Package diagrams
   main_package:
     include!: uml/package/main_package.yml
+  architecture_package:
+    include!: uml/package/architecture_package.yml
   # Include diagrams
   include_graph:
     include!: uml/include/include.yml

Makefile

@@ -142,6 +142,9 @@ docs:
 doxygen: docs
 	cp CONTRIBUTING.md docs/contributing.md
 	cp CHANGELOG.md docs/changelog.md
+	cp docs/diagrams/*.svg docs/doxygen/
+	mkdir -p docs/doxygen/html/test_cases
+	cp docs/test_cases/*.svg docs/doxygen/html/test_cases/
 	../doxygen/_build/bin/doxygen
 
 .PHONY: fedora/%

docs/Makefile

@@ -19,6 +19,7 @@ UPDATE_TOC := markdown-toc  --bullets "*" -i
 
 .PHONY: toc
 toc:
+		$(UPDATE_TOC) architecture.md
 		$(UPDATE_TOC) class_diagrams.md
 		$(UPDATE_TOC) comment_decorators.md
 		$(UPDATE_TOC) common_options.md

docs/architecture.md

@@ -1,2 +1,202 @@
 # Architecture
 
+<!-- toc -->
+
+* [Overview](#overview)
+* [Configuration model](#configuration-model)
+* [Diagram model](#diagram-model)
+  * [Common model](#common-model)
+  * [Diagram filters](#diagram-filters)
+* [Translation unit visitors](#translation-unit-visitors)
+* [Diagram generators](#diagram-generators)
+* [Command line handler](#command-line-handler)
+* [Tests](#tests)
+  * [Unit tests](#unit-tests)
+  * [Test cases](#test-cases)
+  * [Real code tests](#real-code-tests)
+
+<!-- tocstop -->
+
+This section presents general architecture and components of `clang-uml`.
+
+> All diagrams below are generated by `clang-uml` and updated automatically.
+
+## Overview
+
+`clang-uml` is written in C++17 and
+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.
+
+The code is divided into several packages (namespaces), the main of them are:
+
+- [`clanguml::config`](./namespaceclanguml_1_1config.html) - configuration
+  handling
+- [`clanguml::common`](./namespaceclanguml_1_1common.html) - common interfaces
+- [`clanguml::class_diagram`](./namespaceclanguml_1_1class__diagram.html) -
+  specializations for class diagrams
+- [`clanguml::sequence_diagram`](./namespaceclanguml_1_1sequence__diagram.html) -
+  specializations for sequence diagrams
+- [`clanguml::include_diagram`](./namespaceclanguml_1_1include__diagram.html) -
+  specializations for include diagrams
+- [`clanguml::package_diagram`](./namespaceclanguml_1_1package__diagram.html) -
+  specializations for package diagrams
+
+![clang-uml packages](./architecture_package.svg)
+
+## Configuration model
+
+The configuration model consists of classes representing the configuration
+specified in the YAML configuration files.
+
+Depending on the option, it can either:
+
+- be specified only at the top level of the configuration file
+- only in the specific diagram configuration
+- either of the above
+
+The first group of options are stored in
+the [`config::config`](structclanguml_1_1config_1_1config.html) class.
+
+The second group is stored in a specific diagram config subclass, e.g.
+[`config::sequence_diagram`](structclanguml_1_1config_1_1sequence__diagram.html)
+
+The options in the last group are modeled in the
+[`config::inheritable_diagram_options`](./structclanguml_1_1config_1_1inheritable__diagram__options.html).
+
+![configuration model](./config_class.svg)
+
+The YAML configuration file is parsed
+using [yaml-cpp](https://github.com/jbeder/yaml-cpp) library:
+
+![configuration load sequence](./load_config_sequence.svg)
+
+For each possible option type, there must an implementation of a
+YAML decoder - e.g.
+[`YAML::convert<filter>`](./structYAML_1_1convert_3_01filter_01_4.html)
+(for converting YAML nodes to configuration model classes)
+and a YAML emitter - e.g.
+[`operator<<`](./group__yaml__emitters.html#ga4c8bc075684b08daa379aef609bb6297)
+(for generating YAML from configuration model classes).
+
+## Diagram model
+
+The diagram model namespace is divided into the [`common`](#common-model) model
+namespace and 1 namespace for each supported diagram type.
+
+![clang-uml packages](./architecture_model.svg)
+
+### Common model
+
+The [common diagram model namespace](./namespaceclanguml_1_1common_1_1model.html),
+provides a set of classes representing typical UML and C++ concepts such as
+diagram elements, packages, templates, and others which are shared by more than
+1 diagram type.
+
+![clang-uml packages](./common_model_class.svg)
+
+The diagram elements are composed into a hierarchy spanning all major
+namespaces,
+depending on whether the element is specific for a single diagram type (
+e.g. [`participant`](./structclanguml_1_1sequence__diagram_1_1model_1_1participant.html)),
+or whether it's common for several diagram types (
+e.g. [`package`](./classclanguml_1_1common_1_1model_1_1package.html)).
+
+### Diagram filters
+
+In order to ease the generation of diagrams, `clang-uml` has a (very) simple
+intermediate UML model, which covers only the features necessary for
+generation of the supported diagram types. The model can be extended if
+necessary to add new features.
+
+![diagram filter context](./diagram_filter_context_class.svg)
+
+## Translation unit visitors
+
+The first stage in the diagram generation involves traversing the AST of
+each translation unit from the `compile_commands.json` compilation database,
+which matched at least one pattern specified in the `glob` pattern of the
+configuration file.
+
+Each visitor is implemented in a subclass of
+[`translation_unit_visitor`](./classclanguml_1_1common_1_1visitor_1_1translation__unit__visitor.html),
+and must also implement relevant methods from Clang's
+[RecursiveASTVisitor](https://clang.llvm.org/doxygen/classclang_1_1RecursiveASTVisitor.html).
+
+![AST visitors](./architecture_visitors_class.svg)
+
+The output of the `translation_unit_visitor` for each diagram type is an
+intermediate diagram model, which is then passed to the relevant diagram
+generator.
+
+## Diagram generators
+
+Diagram generators convert the `clang-uml`'s internal UML model into actual
+diagram in one of the supported formats:
+
+- PlantUML
+- JSON
+
+Each diagram generator extends a common interface appropriate for the
+selected output format, i.e.:
+
+- [PlantUML](classclanguml_1_1common_1_1generators_1_1plantuml_1_1generator.html)
+- [JSON](classclanguml_1_1common_1_1generators_1_1json_1_1generator.html)
+
+and renders the output to a file. For each diagram type there is a separate
+generator for each supported output format.
+
+## Command line handler
+
+The [cli_handler](classclanguml_1_1cli_1_1cli__handler.html) is a command line
+handler class is a wrapper around [CLI11](https://github.com/CLIUtils/CLI11),
+and implements handlers for various actions, validates command line parameters
+and reports errors.
+
+## Tests
+
+### Unit tests
+
+Basic set of units tests are stored in
+[tests/test_*.cc](https://github.com/bkryza/clang-uml/tree/master/tests)
+test files. The unit tests do not aim to cover the entire codebase, only
+specific algorithms or methods, which should behave as expected and if their
+errors can be difficult to diagnose when running the test cases on C++ code.
+
+### Test cases
+
+These tests are the main tests of `clang-uml`. Each test case tests one or
+more feature of a specific diagram type. Each of them has a separated directory
+in the `tests` directory and its own `.clang-uml` with diagram configuration
+as well as a `test_case.h` file which contains the tests assertions.
+
+Any other sources in that directory are compiled and then used to generate the
+diagrams, whose contents should be then verified within `test_case.h` 
+for correctness. All the sources should be wrapped within a namespace:
+`clanguml::`
+
+These test directories are numbered in consecutive numbers using the following
+convention:
+- Start with a letter `t`
+- The first digit of the number is the diagram type:
+  - `0` - class diagram
+  - `2` - sequence diagram
+  - `3` - package diagram
+  - `4` - include diagram
+  - `9` - other test cases
+- The rest of the name is the consecutive number of the test case
+
+Each test case is also referenced in
+[test_cases.yaml](https://github.com/bkryza/clang-uml/blob/master/tests/test_cases.yaml)
+where it has assigned a title. That file is used to generate the [test cases 
+documentation page](./md_docs_2test__cases.html).
+
+### Real code tests
+
+Each release is tested on a set of open-source C++ projects, to be sure that
+at least the new version does not crash or introduce some obvious regressions.
+
+The tests are stored in a separate
+repository: [clang-uml-examples](https://github.com/bkryza/clang-uml-examples).
+

docs/common_options.md

@@ -21,7 +21,7 @@ from it. The file must be specified in YAML and it's overall structure is as fol
 # common options for all diagrams
 ...
 diagrams:
-  first_diagram_name>:
+  first_diagram_name:
     type: class|sequence|package|include
     # diagram specific options
     ...

docs/doxygen/layout-clang-uml.xml

@@ -30,11 +30,11 @@
       <tab type="structlist" visible="yes" title="" intro=""/>
       <tab type="structindex" visible="$ALPHABETICAL_INDEX" title=""/>
     </tab>
-    <tab type="exceptions" visible="yes" title="">
+<!--    <tab type="exceptions" visible="yes" title="">-->
-      <tab type="exceptionlist" visible="yes" title="" intro=""/>
+<!--      <tab type="exceptionlist" visible="yes" title="" intro=""/>-->
-      <tab type="exceptionindex" visible="$ALPHABETICAL_INDEX" title=""/>
+<!--      <tab type="exceptionindex" visible="$ALPHABETICAL_INDEX" title=""/>-->
-      <tab type="exceptionhierarchy" visible="yes" title="" intro=""/>
+<!--      <tab type="exceptionhierarchy" visible="yes" title="" intro=""/>-->
-    </tab>
+<!--    </tab>-->
     <tab type="files" visible="yes" title="">
       <tab type="filelist" visible="yes" title="" intro=""/>
       <tab type="globals" visible="yes" title="" intro=""/>
@@ -46,6 +46,7 @@
   <!-- Layout definition for a class page -->
   <class>
     <briefdescription visible="yes"/>
+    <detaileddescription title=""/>
     <includes visible="$SHOW_HEADERFILE"/>
     <inheritancegraph visible="$CLASS_GRAPH"/>
     <collaborationgraph visible="$COLLABORATION_GRAPH"/>
@@ -83,7 +84,6 @@
       <related title="" subtitle=""/>
       <membergroups visible="yes"/>
     </memberdecl>
-    <detaileddescription title=""/>
     <memberdef>
       <inlineclasses title=""/>
       <typedefs title=""/>
@@ -105,6 +105,7 @@
   <!-- Layout definition for a namespace page -->
   <namespace>
     <briefdescription visible="yes"/>
+    <detaileddescription title=""/>
     <memberdecl>
       <nestednamespaces visible="yes" title=""/>
       <constantgroups visible="yes" title=""/>
@@ -121,7 +122,6 @@
       <variables title=""/>
       <membergroups visible="yes"/>
     </memberdecl>
-    <detaileddescription title=""/>
     <memberdef>
       <inlineclasses title=""/>
       <typedefs title=""/>
@@ -137,6 +137,7 @@
   <!-- Layout definition for a concept page -->
   <concept>
     <briefdescription visible="yes"/>
+    <detaileddescription title=""/>
     <includes visible="$SHOW_HEADERFILE"/>
     <definition visible="yes" title=""/>
     <detaileddescription title=""/>
@@ -146,6 +147,7 @@
   <!-- Layout definition for a file page -->
   <file>
     <briefdescription visible="yes"/>
+<!--    <detaileddescription title=""/>-->
     <includes visible="$SHOW_INCLUDE_FILES"/>
     <includegraph visible="$INCLUDE_GRAPH"/>
     <includedbygraph visible="$INCLUDED_BY_GRAPH"/>
@@ -167,7 +169,6 @@
       <variables title=""/>
       <membergroups visible="yes"/>
     </memberdecl>
-    <detaileddescription title=""/>
     <memberdef>
       <inlineclasses title=""/>
       <defines title=""/>
@@ -184,6 +185,7 @@
   <!-- Layout definition for a group page -->
   <group>
     <briefdescription visible="yes"/>
+    <detaileddescription title=""/>
     <groupgraph visible="$GROUP_GRAPHS"/>
     <memberdecl>
       <nestedgroups visible="yes" title=""/>
@@ -209,7 +211,6 @@
       <friends title=""/>
       <membergroups visible="yes"/>
     </memberdecl>
-    <detaileddescription title=""/>
     <memberdef>
       <pagedocs/>
       <inlineclasses title=""/>
@@ -240,6 +241,6 @@
       <dirs visible="yes"/>
       <files visible="yes"/>
     </memberdecl>
-    <detaileddescription title=""/>
+<!--    <detaileddescription title=""/>-->
   </directory>
 </doxygenlayout>

docs/doxygen_integration.md

@@ -6,10 +6,12 @@
 
 <!-- tocstop -->
 
-`clang-uml` diagrams can be easily added to the Doxygen documentation using the image tag, however
+`clang-uml` diagrams can be easily added to the Doxygen documentation using the
-[Doxygen](https://www.doxygen.nl/index.html) does not support the `clang-uml` specific commands.
+`image` tag, however [Doxygen](https://www.doxygen.nl/index.html) does not
+support the `clang-uml` specific [commands](./comment_decorators.md), which 
+will  appear in the documentation unprocessed.
 
-`clang-uml` decorators can be omitted completely in Doxygen, by adding the
+The best solution to this is to tell Doxygen to ignore them, by adding the
 following lines to the Doxygen config file:
 
 ```
@@ -18,3 +20,43 @@ ALIASES                += uml{1}=""
 ALIASES                += uml{2}=""
 ALIASES                += uml{3}=""
 ```
+
+Furthermore, Doxygen adds images to HTML documentation as `<img src=""/>`,
+which disables interactive links in SVG diagrams. One way to go around it
+is to use a special command for these images, for instance:
+
+```
+ALIASES                += embed{1}="\htmlonly <embed src=\"\1\"/> \endhtmlonly"
+```
+
+and then use the following in the source code comments:
+
+```cpp
+/**
+ * @brief Base class for all diagram models
+ *
+ * @embed{diagram_hierarchy_class.svg}
+ */
+class diagram {
+public:
+// ...
+```
+
+This directive in the configuration file will add the SVG diagrams using
+`<embed>` HTML tag, and enable the links in the diagram on most browsers.
+
+Finally, to have `clang-uml` generate links from diagram elements such as classes
+or packages to Doxygen pages, it is only necessary to add the following
+configuration file option:
+
+```yaml
+generate_links:
+  link: "{% if existsIn(element, \"doxygen_link\") %}{{ element.doxygen_link }}{% endif %}"
+  tooltip: "{% if existsIn(element, \"comment\") and existsIn(element.comment, \"brief\") %}{{ abbrv(trim(replace(element.comment.brief.0, \"\\n+\", \" \")), 256) }}{% else %}{{ element.name }}{% endif %}"
+```
+
+This option will tell `clang-uml` to generate a link to a local Doxygen
+documentation page, provided that it is possible to generate it. Currently,
+this only works for diagram elements, it will not work for instance
+for individual methods.
+

docs/installation.md

@@ -30,12 +30,16 @@ sudo apt install clang-uml
 
 ```bash
 # Fedora 36
-wget https://github.com/bkryza/clang-uml/releases/download/0.3.1/clang-uml-0.3.1-1.fc36.x86_64.rpm
+wget https://github.com/bkryza/clang-uml/releases/download/0.3.7/clang-uml-0.3.7-1.fc36.x86_64.rpm
-sudo dnf install ./clang-uml-0.3.1-1.fc36.x86_64.rpm
+sudo dnf install ./clang-uml-0.3.7-1.fc36.x86_64.rpm
 
 # Fedora 37
-wget https://github.com/bkryza/clang-uml/releases/download/0.3.1/clang-uml-0.3.1-1.fc37.x86_64.rpm
+wget https://github.com/bkryza/clang-uml/releases/download/0.3.7/clang-uml-0.3.7-1.fc37.x86_64.rpm
-sudo dnf install ./clang-uml-0.3.1-1.fc37.x86_64.rpm
+sudo dnf install ./clang-uml-0.3.7-1.fc37.x86_64.rpm
+
+# Fedora 38
+wget https://github.com/bkryza/clang-uml/releases/download/0.3.7/clang-uml-0.3.7-1.fc38.x86_64.rpm
+sudo dnf install ./clang-uml-0.3.7-1.fc38.x86_64.rpm
 ```
 
 #### Conda

docs/package_diagrams.md

@@ -31,7 +31,7 @@ diagrams:
 ```
 
 For instance the following C++ code:
-```
+```cpp
 namespace A::AA {
 namespace A1 {
 struct CA {
@@ -152,7 +152,7 @@ template <typename T> std::map<T, std::shared_ptr<A::AA::A13::CM>> cm()
 }
 ```
 
-generates the following diagram:
+results the following diagram:
 
 ![package_deps](./test_cases/t30002_package.svg)
 

docs/troubleshooting.md

@@ -27,6 +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.:
+
 ```bash
 make debug
 ```
@@ -48,7 +49,9 @@ paste the stack trace and few last logs from the console.
 
 ### Diagram generation is very slow
 
-`clang-uml` uses Clang's [RecursiveASTVisitor](https://clang.llvm.org/doxygen/classclang_1_1RecursiveASTVisitor.html), to
+`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
 translation unit (i.e. each entry in your `compile_commands.json`), including
 all of their header dependencies recursively. This means, that for large code
@@ -61,7 +64,8 @@ a single diagram usually can be found in just a few translation units, or even
 a single one.
 
 This is where the `glob` configuration parameter comes in. It can be used to
-limit the number of translation units to visit for a given diagram, for instance:
+limit the number of translation units to visit for a given diagram, for
+instance:
 
 ```yaml
 diagrams:
@@ -197,6 +201,7 @@ yq 'explode(.)' .clang-uml | clang-uml --config -
 ```
 
 ## Class diagrams
+
 ### "fatal error: 'stddef.h' file not found"
 
 This error means that Clang cannot find some standard headers in include
@@ -253,12 +258,18 @@ clang-uml --add-compile-flag -I/opt/my_toolchain/include \
           --remove-compile-flag -I/usr/include ...
 ```
 
+Also see
+[here](./md_docs_2common__options.html#resolving-include-path-and-compiler-flags-issues).
+
 ### How can I generate class diagram of my entire project
+
 I want to generate a diagram containing all classes and relationships in my
 project - I don't care how big it is going to be.
 
-Of course this is possible, the best way to do this is to specify that `clang-uml`
+Of course this is possible, the best way to do this is to specify
-should only include elements defined in files contained in project sources, e.g.:
+that `clang-uml`
+should only include elements defined in files contained in project sources,
+e.g.:
 
 ```yaml
 diagrams:
@@ -277,6 +288,7 @@ clang-uml -g json -n all_classes --progress
 ```
 
 ### Cannot generate classes for 'std' namespace
+
 Currently, system headers are skipped automatically by `clang-uml`, due to
 too many errors they produce when generating diagrams, especially when trying
 to process `GCC`'s or `MSVC`'s system headers by `Clang` - not yet sure why

uml/class/architecture_visitors_class.yml

@@ -0,0 +1,16 @@
+type: class
+generate_packages: true
+glob:
+  - src/docs/architecture.cc
+include:
+  namespaces:
+    - clanguml
+  elements:
+    - r: "clanguml::.+::translation_unit_visitor.*"
+    - r: "clanguml::.+::model::diagram"
+exclude:
+  access: [ public, protected, private ]
+  relationships: [ dependency ]
+plantuml:
+  before:
+    - title clang-uml top level architecture - AST visitors

uml/class/common_model_class.yml

@@ -8,8 +8,15 @@ include:
 exclude:
   relationships:
     - dependency
+  subclasses:
+    - clanguml::common::model::filter_visitor
+  access: [public, protected, private]
+  element_types:
+    - enum
 using_namespace:
   - clanguml::common::model
 plantuml:
   before:
     - 'title clang-uml common diagram model'
+  after:
+    - 'note top of {{ alias("diagram") }}: Common class for specific diagram types'

uml/class/config_class.yml

@@ -1,12 +1,26 @@
 type: class
-include_relations_also_as_members: false
+include_relations_also_as_members: true
 glob:
   - src/config/config.cc
 include:
   namespaces:
     - clanguml::config
+  context:
+    - clanguml::config::inheritable_diagram_options
+    - clanguml::config::config
+    - clanguml::config::diagram
+exclude:
+  elements:
+    - r: "clanguml::config::option<.*>"
 using_namespace:
   - clanguml::config
 plantuml:
   before:
     - 'title clang-uml configuration model'
+  after:
+    - 'note left of {{ alias("inheritable_diagram_options") }}: Options common to all diagram types.'
+    - 'note right of {{ alias("config") }}: General options not used by diagrams.'
+    - 'note bottom of {{ alias("class_diagram") }}: Options for specific class diagrams'
+    - 'note bottom of {{ alias("sequence_diagram") }}: Options for specific sequence diagrams'
+    - 'note bottom of {{ alias("package_diagram") }}: Options for specific package diagrams'
+    - 'note bottom of {{ alias("include_diagram") }}: Options for specific include diagrams'

uml/class/diagram_filter_context_class.yml

@@ -1,6 +1,6 @@
 type: class
 include_relations_also_as_members: true
-generate_packages: true
+generate_packages: false
 glob:
   - src/common/model/diagram_filter.cc
   - src/common/model/diagram.cc
@@ -12,5 +12,9 @@ include:
 exclude:
   elements:
     - clanguml::common::model::path
+  method_types:
+    - constructor
+    - destructor
+    - operator
 using_namespace:
   - clanguml

uml/package/architecture_package.yml

@@ -0,0 +1,21 @@
+type: package
+glob:
+  - src/config/config.cc
+  - src/common/model/diagram.cc
+  - src/**/model/diagram.cc
+  - src/**/visitor/translation_unit_visitor.cc
+  - src/**/generators/**/*generator.cc
+include:
+  namespaces:
+    - clanguml
+  elements:
+    - clanguml
+    - clanguml::common
+    - clanguml::config
+    - r: "clanguml::.+_diagram"
+    - r: "clanguml::.+::model"
+    - r: "clanguml::.+::visitor"
+    - r: "clanguml::.+::generators"
+plantuml:
+  before:
+    - 'title clang-uml top level packages'