mirror of
https://github.com/twigphp/Twig.git
synced 2026-09-17 12:57:05 +00:00
Fabien Potencier
36b8920932
This PR was squashed before being merged into the 3.x branch.
Discussion
----------
Attach documentation comments to nodes
Alternatives to #4870
To avoid BC breaks, I have another idea, using `##` as a new syntax, a bit like `/** */` in PHP vs `/* */`.
"Documentation" is attached as metadata to the next relevant node:
```twig
{## The main content displayed on the page #}
{% block content %}
...
{% endblock %}
```
Documentation comments can also describe variables declared with the `types` tag:
```twig
{% types {
## The unique identifier of the article
id: 'string',
## Whether the article should be highlighted
featured?: 'boolean',
} %}
```
Node visitors can access this metadata through `Node::getDocumentation()`, allowing IDEs, static analyzers, and documentation generators to consume it without affecting template rendering. Documentation is preserved when visitors or optimizations replace nodes.
Closes #4768
Closes #4870
Commits
-------
6806e30474 Attach documentation comments to nodes
Twig, the flexible, fast, and secure template language for PHP
==============================================================
Twig is a template language for PHP.
Twig uses a syntax similar to the Django and Jinja template languages which
inspired the Twig runtime environment.
Sponsors
--------
.. raw:: html
<a href="https://docs.blackfire.io/introduction?utm_source=twig&utm_medium=github_readme&utm_campaign=logo">
<img src="https://static.blackfire.io/assets/intemporals/logo/png/blackfire-io_secondary_horizontal_transparent.png?1" width="255px" alt="Blackfire.io">
</a>
More Information
----------------
Read the `documentation`_ for more information.
.. _documentation: https://twig.symfony.com/documentation