---
title: "New in Twig 3.29: Documentation Comments (Symfony Blog)"
url: https://daily.dev/posts/new-in-twig-3-29-documentation-comments-symfony-blog--yr4rbofie
source_url: https://symfony.com/blog/new-in-twig-3-29-documentation-comments
type: article
source: "Symfony"
published: 2026-08-21T15:12:18.758Z
updated: 2026-08-21T15:24:25.857Z
tags: ["php", "symfony"]
reading_time: 4
upvotes: 1
comments: 0
language: en
---

> ## Documentation Index
> Fetch the complete documentation index at: https://daily.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# New in Twig 3.29: Documentation Comments (Symfony Blog)

**[Symfony](https://daily.dev/sources/symfony)** · 4 min read · 1 upvotes · 0 comments

## Summary

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.

## Full article

daily.dev links to this article rather than hosting it. Read it at the original source: <https://symfony.com/blog/new-in-twig-3-29-documentation-comments>

## Questions 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._

## Similar posts on daily.dev

- [Twig 3.28.0 released \(Symfony Blog\)](https://daily.dev/posts/twig-3-28-0-released-symfony-blog--dpjk2dnjm) · Symfony · 4 upvotes · 0 comments
- [New in Twig 4.0: A New Macro System \(Symfony Blog\)](https://daily.dev/posts/new-in-twig-4-0-a-new-macro-system-symfony-blog--iohnteuqx) · Symfony · 6 upvotes · 1 comments
- [Twig 3.23: Introducing new operators and destructuring support \(Symfony Blog\)](https://daily.dev/posts/twig-3-23-introducing-new-operators-and-destructuring-support-symfony-blog--bk2cqn0wr) · Symfony · 0 upvotes · 0 comments

---

Tags: [#php](https://daily.dev/tags/php), [#symfony](https://daily.dev/tags/symfony)

[View this post on daily.dev](https://daily.dev/posts/new-in-twig-3-29-documentation-comments-symfony-blog--yr4rbofie)