Standardize Twig comment annotations for documenting template variables and blocks

[Kocal]

For Symfony UX Toolkit, I've been using a simple format to document TwigComponent APIs directly in Twig comments:

{# @prop id string Unique identifier for the Accordion #}
{# @prop multiple boolean Whether multiple items can be opened at once #}
{# @prop defaultValue string|array<string>|null Value(s) of the item(s) to open by default #}
{# @block content The accordion items #}

Live example: https://ux.symfony.com/toolkit/kits/shadcn/components/accordion#content-api-reference

This format is human-readable and easy to parse. It's inspired by PHPDoc's @property, though with a different order: @prop <name> <type> <description> instead of @property <type> $<name> <description>.
It was a mistake, and will be fixed ASAP.

Why standardize?

I've opened Haehnchen/idea-php-symfony2-plugin#2545 to add syntax highlighting for @prop (or @property) and @block in the PhpStorm Symfony plugin.

It would be better to standardize the format first, especially before implementing auto-completion.

Beyond Symfony UX, I think this could be useful for plain Twig templates too.
For instance, @prop could help IDEs suggest variables when using {{ include() }}:

{# _card.html.twig #}
{# @prop title string The title #}
{# @prop description string|null The description #}

{# IDE could auto-suggest 'title' and 'description' here: #}
{{ include('_card.html.twig', { ... }) }}

In the future, we can even imagine deprecating templates with a @deprecated annotation, etc...

WDYT? Thanks!

[fabpot]

Thanks for the suggestion! I think we already have most of what you need with existing Twig tags.

For variables, we already have {% types %}.

   {% types {
       id: 'string',
       multiple: 'boolean',
       defaultValue: 'string|array<string>|null',
   } %}

For deprecation, we have {% deprecated %}.

   {% deprecated 'Use "layout.html.twig" instead.' package='foo/bar' version='1.1' %}

The only missing thing AFAIU is descriptions.

But we could extend it with a docs option on each entry:

   {% types {
       id: 'string' docs="Unique identifier for the Accordion",
       multiple?: 'boolean' docs="Whether multiple items can be opened at once",
       defaultValue: 'string|array<string>|null',
   } %}

And for block documentation, we could extend the {% block %} tag the same way:

   {% block content docs="The accordion items" %}
       ...
   {% endblock %}

Would that work for you?

[Kocal]

That's a very elegant alternative; I didn't think about that syntax at all.
Maybe... description instead of docs? IDK 🤷🏻

I'm a little concerned about modifying existing tags (I'm very far from being a Twig expert). Couldn't that cause problems? For example, what if a Symfony app (with a Twig version that does not supported documented types/blocks) installs a UX Toolkit recipe (which create Twig files in its templates/ directory), could it break its app, or it can be silently ignored?

[fabpot]

I used docs as a wink to phpdocs, but open to another suggestion, maybe description is a bit too long, desc might be a bit better.

You're right about BC.