Add support for docs property for BlockNode and TypesNode

[Kocal]

Close #4768

(Code generated almost entirely using Claude Opus 4.5.)

The following code is now valid (essential parts of our UX Toolkit Shadcn Button component):

{%- types {
    variant: "'default'|'secondary'|'destructive'|'outline'|'ghost'|'link'" docs="Visual style variant.",
    size: "'default'|'xs'|'sm'|'lg'|'icon'|'icon-xs'|'icon-sm'|'icon-lg'" docs="The button size.",
    button: '"button"' docs="The HTML tag to render.",
} -%}

{%- block content docs="The button label and/or icon" %}{% endblock -%}

[Kocal]

I think it could be a nice addition, it costs nothing:

[stof]

With the introduction of the assignment operator, I think this proposal is ambiguous for blocks as {% block content docs="Hello world!" %} is a valid code already, using docs="Hello world!" as the expression (even though assigning a docs variable in that scope is quite useless, as the block is the scope boundary)

[stof]

This need to handle cases where the content of the attribute contains */, to make sure it does not ends the PHP comment.

[stof]

this is breaking existing code if the block is using an expression starting with a docs variable or function.

I think it needs to be parsed after the expression, not before it, for the case using the expression-based content.

[willrowe]

I think desc or description would be more clear than docs.

[Kocal]

I think this proposal is ambiguous for blocks as {% block content docs="Hello world!" %} is a valid code already

Are you sure? Because using {%- block content docs="The button label and/or icon" %}{% endblock -%} on 3.x gives me Unknown "endblock" tag in components/Button.html.twig at line 35.:

Or did I miss something?

[stof]

@Kocal the {% endblock %} tag is forbidden when using the shortcut in the start tag. But the switch between both variants is done purely based on the start tag (we need to know the variant before trying to parse the tag body as only one variant has it).
What is valid on 3.x is {%- block content docs="The button label and/or icon" %}