clang-uml/docs/class_diagrams.md

Generating class diagrams

• Classes and their properties
  • Excluding private or protected members from the diagram
• Relationships
  • Relationships to classes in containers or smart pointers
• Inheritance diagrams
• Namespaces as packages
• Class context diagram
• Disabling dependency relationships

The minimal config required to generate a class diagram is presented below:

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

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:

    include:
      access:
        - public

To render only classes without any properties an exclusion filter can be added:

    exclude:
      access:
        - public
        - protected
        - private

Relationships

The following table presents the PlantUML arrows representing each relationship in the class diagrams.

UML	PlantUML
Inheritance
Association
Dependency
Aggregation
Composition
Template specialization/instantiation
Nesting (inner class/enum)

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:

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:

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:

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:

    include:
      subclasses:
        - clanguml::t00039::A
      relationships:
        - inheritance

Namespaces as packages

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:

generate_packages: true

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:

    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:

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:

    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.