clang-uml/docs/class_diagrams.md

# Generating class diagrams

<!-- toc -->

* [Classes and their properties](#classes-and-their-properties)
  * [Excluding private or protected members from the diagram](#excluding-private-or-protected-members-from-the-diagram)
* [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)
* [Class context diagram](#class-context-diagram)
* [Disabling dependency relationships](#disabling-dependency-relationships)

<!-- tocstop -->

The minimal config required to generate a class 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: puml
# Diagrams definitions
diagrams:
  # Diagram name
  t00002_class:
    # Type of diagram (has to be `class`)
    type: class
    # Include only translation units matching the following patterns
    glob:
      - src/*.cc
    # Render all names in the diagram relative to specific namespace
    using_namespace:
      - ns1
    # Include only classes from specific namespace
    include:
      namespaces:
        - ns1::ns2
```

## Classes and their properties
The basic class diagram generated by `clang-uml` and rendered using PlantUML looks like this:

![extension](test_cases/t00003_class.svg)

Member types and method return types are rendered at the end after `:` sign.

Static methods and members are underlined.

In case method argument lists are too long and not required for diagram readability, they can be suppressed completely 
or abbreviated by setting `generate_method_arguments` option to either `none`, `abbreviated` or `full` (default).


### Excluding private or protected members from the diagram
In order to only include public members in the class diagrams, we can add the following inclusion filters:
```yaml
    include:
      access:
        - public
```

To render only classes without any properties an exclusion filter can be added:
```yaml
    exclude:
      access:
        - public
        - protected
        - private
```

## Relationships

The following table presents the PlantUML arrows representing each relationship 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) |


By default, a member from which a relationship has been added to the diagram between 2 classes will also be rendered
inside the class. This behaviour can be however disabled by adding the following option to the
diagram definition:
```yaml
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 and still generate
relationship between these classes, for instance the following code:

```cpp
class A { };

class B { };

class C { };

class R {
public:
    std::unique_ptr<A> a;
    std::shared_ptr<B> b;
    std::weak_ptr<C> c;
};
```

generates the following diagram:

![extension](test_cases/t00007_class.svg)

## Inheritance diagrams

A common type of class diagram is an inheritance diagram, where only subclasses of a specific base class are
included and only the inheritance relationships are rendered. This can be easily achieved in `clang-uml` through
inclusion filters:
```yaml
    include:
      subclasses:
        - clanguml::t00039::A
      relationships:
        - inheritance
```

## Including 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 following option must be set to `true`:

```yaml
generate_packages: true
```

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:

```yaml
package_type: directory
```

which results in the following diagram:

![t00065_class](test_cases/t00065_class.svg)

> In this case make sure that the root path of the configuration file is properly configured
> for your project, if necessary add `relative_to` option to denote the root path
> against which all relative paths in the config file are calculated.

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

```yaml
    include:
      context:
        - ns1::MyClass
```

## Disabling dependency relationships
In many cases, dependency relationships between classes can clutter the diagram too much, for instance consider this
diagram:

![t00019_class](test_cases/t00019_class.svg)

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:
      relationships:
        - dependency
```

Dependency relationships are inferred whenever a class uses another class, thus often dependency relationship
will be rendered in addition to other relationships such as association or inheritance. In the future there might
be an option to remove the redundant dependency relationships from the diagram automatically.