Configuration file reference

Top level options

compilation_database_dir - path to the directory containing compile_commands.json
output_directory - path to the directory where PlantUML diagrams will be generated
diagrams - the map of diagrams to be generated, each diagram name is provided as the key of the diagram YAML node

Diagram options

type - type of diagram, one of [class, sequence, package, include]
glob - list of glob patterns to match source code files for analysis
include_relations_also_as_members - when set to false, class members for relationships are rendered in UML are skipped from class definition (default: true)
generate_method_arguments - determines whether the class diagrams methods contain full arguments (full), are abbreviated (abbreviated) or skipped (none)
using_namespace - similar to C++ using namespace, a A::B value here will render a class A::B::C::MyClass in the diagram as C::MyClass, at most 1 value is supported
include - definition of inclusion patterns:
- namespaces - list of namespaces to include
- relationships - list of relationships to include
- elements - list of elements, i.e. specific classes, enums, templates to include
- access - list of visibility scopes to include (e.g. private)
- subclasses - include only subclasses of specified classes (and themselves)
- specializations - include all specializations or instantiations of a given template
- dependants - include all classes, which depend on the specified class
- dependencies - include all classes, which are dependencies of the specified class
- context - include only entities in direct relationship with specified classes
exclude - definition of excqlusion patterns:
- namespaces - list of namespaces to exclude
- relationships - list of relationships to exclude
- elements - list of elements, i.e. specific classes, enums, templates to exclude
- access - list of visibility scopes to exclude (e.g. private)
- subclasses - exclude subclasses of specified classes (and themselves)
- specializations - exclude all specializations or instantiations of a given template
- dependants - exclude all classes, which depend on the specified class
- dependencies - exclude all classes, which are dependencies of the specified class
- context - exclude only entities in direct relationship with specified classes
layout - add layout hints for entities (classes, packages)
plantuml - verbatim PlantUML directives which should be added to a diagram
- before - list of directives which will be added before the generated diagram
- after - list of directives which will be added after the generated diagram

Template engine

clang-uml integrates inja template engine, with several additional functions which can be used in textual directives within the configuration files, notes and to generate links and tooltips to diagrams.

The following, are the clang-uml additional template functions:

ltrim(string) - left trims a string
rtrim(string) - right trims a string
trim(string) - trims a string
substr(string, offset, length) - returns a substring of a string from offset of length
split(string) - splits a string and returns a list of strings
replace(string, regex, replacement) - returns a string with replace matches to regex with replacement string
abbrv(string, length) - returns a string truncated to length including trailing ellipsis
element(string) - returns the entire JSON context a given diagram element, including the following properties:
- name - name of the element
- type - type of diagram element (e.g. class, enum, package)
- namespace - fully qualified element namespace
- full_name - fully qualified element name
- comment [optional] - elements comment, if any
- alias - internal diagram element alias (e.g. PlantUML alias)
alias(string) - returns a PlantUML alias of an C++ entity represented by string name
comment(string) - returns a comment of an C++ entity represented by string name

Templates allow complex postprocessing of the diagrams, for instance creation of customized PlantUML notes in the diagrams from comments in the code. Below is an example of using the above commands to generate notes in the PlantUML diagram from code comments (see also test case t00050):

    plantuml:
      after:
        # Add a note left of the `A` class with the entire clas comment as content
        - >
           note left of {{ alias("A") }}
              {{ comment("clanguml::t00050::A").formatted }}
           end note
        # Same as above
        - >
          note right of {{ element("clanguml::t00050::A").alias }}
             {% set e=element("clanguml::t00050::A") %} {{ e.comment.formatted }}
          end note
        # Add a note left of class 'C' using trimmed text content from the class comment
        - >
          note left of {{ alias("C") }} #AABBCC
             {{ trim(comment("clanguml::t00050::C").text) }}
          end note
        # For each element in the diagram (class, template, enum):
        #  - Add a note with \brief comment if exists
        #  - Add a note with \todo for each element which has it
        #  - Add a note with template parameter descriptions based on \tparam comment
        - >
          {# Render brief comments and todos, if any were written for an element #}
          {% for e in diagram.elements %}
          {% if existsIn(e, "comment") and existsIn(e.comment, "brief") %}

          note top of {{ e.alias }} {% if e.type == "class" %} #22AA22 {% else %} #2222AA {% endif %}
             {% set c=e.comment %} {{ c.brief.0 }}
          end note

          {% endif %}
          {% if existsIn(e, "comment") and existsIn(e.comment, "todo") %}
          {% set c=e.comment %}
          {% for t in c.todo %}
          note top of {{ e.alias }} #882222
             **TODO**
             {{ t }}
          end note

          {% endfor %}

          {% endif %}
          {# Render template paramete if any #}
          {% if existsIn(e, "comment") and existsIn(e.comment, "tparam") %}
          {% set c=e.comment %}

          note top of {{ e.alias }} #AAAAFF
             **Template parameters**
             {% for tp in c.tparam %}
             //{{ tp.name }}// {{ trim(tp.description) }}
             {% endfor %}
          end note

          {% endif %}
          {% endfor %}

Currently there are 2 available comment parsers:

plain - default
clang They can be selected using comment_parser config option.

`plain` comment parser

This parser provides only 2 options to the Jinja context:

comment.raw - raw comment text, including comment markers such as /// or /**
comment.formatted - formatted entire comment

`clang` comment parser

This parser uses Clang comment parsing API to extract commands from the command:

comment.raw - raw comment text, including comment markers such as /// or /**
comment.formatted - formatted entire comment
comment.<command>.<N> - where command is the command used in the command e.g. brief, todo, etc. and N is the index of the command in the array (each comment can have multiple instances of the same command such as \todo)
comment.text - entire text of the comment that is not attached to any command
comment.paragraph.<N> - array of plain text paragraphs, for instance if you don't use \brief commands but often provide brief description as first sentence of the comment separated with a new line from the rest of the comment

Example complete config

# Directory containing the compile_commands.json file
compilation_database_dir: debug
# The directory where *.puml files will be generated
output_directory: docs/diagrams
# Set this as default for all diagrams
generate_method_arguments: none
# Enable generation of hyperlinks to diagram elements
generate_links:
  # Link pattern
  link: "https://github.com/bkryza/clang-uml/blob/{{ git.commit }}/{{ element.source.path }}#L{{ element.source.line }}"
  # Tooltip pattern
  tooltip: "{{ element.name }}"
# The map of diagrams - keys are also diagram file names
diagrams:
  main_package:
    # Include this diagram definition from a separate file
    include!: uml/main_package_diagram.yml
  config_class:
    type: class
    # Do not include rendered relations in the class box
    include_relations_also_as_members: false
    # Limiting the number of files to include can significantly
    # improve the generation time
    glob:
      - src/common/model/*.h
      - src/common/model/*.cc
      - src/class_diagram/model/*.h
      - src/class_diagram/model/*.cc
    include:
      # Only include entities from the following namespaces
      namespaces:
        - clanguml::common::model
        - clanguml::class_diagram::model
      # Only include elements in direct relationship with ClassA
      context:
        - ClassA
    exclude:
      # Do not include private members and methods in the diagram
      access:
        - private
    layout:
      # Add layout hints for PlantUML
      ClassA:
        - up: ClassB
        - left: ClassC
    # Specify customized relationship hints for types which are
    # arguments in template instantiations
    relationship_hints:
      # All tuple arguments should be treated as aggregation
      std::tuple: aggregation
      # All some_template arguments should be treated as associations
      # except for arguments with indexes 2 and 10
      ns1::n2::some_template:
        default: association
        2: composition
        10: aggregation          
    # Entities from this namespace will be shortened
    # (can only contain one element at the moment)
    using_namespace:
      - clanguml::class_diagram::model
    plantuml:
      # Add this line to the beginning of the resulting puml file
      before:
        - 'title clang-uml class diagram model'

9.9 KiB Raw Blame History