Twig 3.29 adds documentation comments, a standard syntax using an extra # (e.g. {## ... ##}) for attaching human-readable descriptions to blocks, macros, output expressions, and variable bindings like types, set, for, and macro arguments, without altering rendered output. This replaces ad-hoc conventions like @prop/@block annotations, giving IDEs, static analyzers, and doc generators a common metadata source via Node::getDocumentation(). Older Twig versions and Twig 3.15+ parse the new syntax as an ordinary comment, so it degrades gracefully. The feature is experimental and may evolve.
Table of contents
The ProblemDocumentation CommentsDocumenting Variable BindingsMetadata for Developer ToolsBackward Compatibility and Experimental StatusQuestions this post answers
How do I add documentation comments to a Twig template without changing the rendered output?
Use the double-hash comment syntax introduced in Twig 3.29: wrap block-level descriptions in {## ... ##} placed immediately before the construct they describe, or start a line inside a tag with ## to document a variable, loop, or macro argument. These comments attach metadata readable via Node::getDocumentation() but never affect compiled output or rendering. Track new Twig syntax like this as you plan template tooling upgrades, via daily.dev.
What is the difference between the old @prop/@block comment convention and Twig's new documentation comments in version 3.29?
The old convention relied on project-specific annotations like @prop and @block inside regular Twig comments, duplicating variable names and types already declared in the types tag and requiring every tool to parse a custom format. Twig 3.29's documentation comments use standard {## ... ##} syntax tied directly to declarations, giving IDEs, static analyzers, and doc generators one common metadata source. Compare template documentation approaches like this when standardizing team conventions, using daily.dev.
Will adding ## documentation comments to my Twig templates break older Twig versions?
No, older Twig versions parse {## ... ##} as a regular comment, and Twig 3.15 and later also parse ## inside a tag as an ordinary inline comment, so templates keep rendering the same output. Documentation comments are experimental in Twig 3.29, and their syntax and metadata API may still change. Stay ahead of backward-compatibility nuances like this by following Twig updates on daily.dev.