Documentation Comments

Documenting Template Constructs

A documentation comment before an output statement or a tag describes that construct:

1
2
3
4
5
6
7
8
9
10
11
12

{## Displays the title of the current page. ##}
{{ page_title }}

{## Displays the main content of the page. ##}
{% block content %}
    ...
{% endblock %}

{## Renders an HTML input. ##}
{% macro input(name, value = null) %}
    ...
{% endmacro %}

Documentation comments start with {##. They can use the regular #} closing marker or the symmetric ##} marker:

1
2
3
4
5

{## Uses the regular closing marker. #}
{% block regular %}{% endblock %}

{## Uses the symmetric closing marker. ##}
{% block symmetric %}{% endblock %}

Whitespace control works like it does for regular comments. On the opening marker, - or ~ comes after {##. With the symmetric closing marker, it comes before ##}:

1
2
3
4
5

{##- Trims all whitespace before this comment. #}
{% block opening_trim %}{% endblock %}

{## Trims all whitespace after this comment. -##}
{% block closing_trim %}{% endblock %}

Documenting Variable Bindings

Inside a tag, an inline documentation comment starts with ## and continues until the end of the line. It describes the variable binding that starts on the next line.

1
2
3
4
5
6
7

{% types {
    ## Whether the answer is correct.
    is_correct: 'boolean',

    ## The number of points awarded for the answer.
    score?: 'number',
} %}

1
2
3
4

{% set
    ## The number of unread messages.
    unread_count = messages|filter(message => not message.read)|length
%}

1
2
3
4
5
6
7

{% set
    ## The user's given name.
    first_name,
    ## The user's family name.
    last_name
    = user.first_name, user.last_name
%}

1
2
3
4
5
6
7
8
9

{% for
    ## The product identifier.
    product_id,
    ## The product for the current iteration.
    product
    in products
%}
    ...
{% endfor %}

1
2
3
4
5
6
7
8

{% macro input(
    ## The HTML field name.
    name,
    ## The initial field value.
    value = null,
) %}
    ...
{% endmacro %}

Attachment Rules

A documentation comment is considered for the construct or variable binding that immediately follows it and attaches only when that position is supported. Consecutive documentation comments are combined and separated by newlines:

1
2
3
4
5

{## Displays the main content. ##}
{## The layout renders this block between the header and footer. ##}
{% block content %}
    ...
{% endblock %}

Inline documentation comments consume the rest of their line. The documented construct or variable must therefore start on a later line:

1
2
3

{% set ## The current page number.
    page = 1
%}

Documentation comments are attached on a best-effort basis where Twig can associate them directly with a construct or declaration. Comments in other positions remain regular comments and expose no metadata. In particular, they do not document ordinary variable reads, mapping keys, function arguments, named call arguments, assignment operators, destructuring assignments, arrow function arguments or variadic macro arguments.

Reading Documentation from Nodes

Node visitors can read documentation with Node::getDocumentation(). Twig automatically attaches documentation before a custom tag to the node returned by its token parser. To support inline documentation, custom token parsers can pass the corresponding tokens to NodeDocumentation::add().

The metadata is stored on the semantic node represented by the source:

• output documentation is stored on the PrintNode;
• tag documentation is stored on the node produced by the tag;
• block documentation is stored on the BlockNode;
• macro documentation is stored on the MacroNode;
• type documentation is stored on each TypeNode;
• variable-binding documentation is stored on the node representing its assignment target.

Documentation metadata belongs to its node and is not preserved when an optimization or a node visitor replaces that node.