Add a docs option to the types and block tags

[Amoifr]

Implements the design proposed by @fabpot in #4768:

• each {% types %} entry accepts an optional docs="..." option after the type string; it is stored in the TypesNode mapping (docs is null when not provided)
• the {% block %} tag accepts an optional docs="..." option after the block name; it is stored as a docs attribute on the BlockNode (new optional constructor argument, BC)

The tags themselves do not use this documentation: it is metadata for tools (IDEs, documentation generators, the Symfony UX Toolkit) that analyze the parsed nodes.

Notes:

• For {% block %}, docs is only treated as an option when followed by =, so the shortcut syntax {% block title docs %} (printing a variable named docs) keeps working; this is covered by a test.
• I kept docs as originally proposed; renaming it to desc is a one-line change if preferred.

Closes #4768

[willrowe]

I like desc better.

[Kocal]

I forgot to close the issue, since I closed the initial PR #4770. We went for symfony/ux#3694 in UX, and also in the PhpStorm plugin Haehnchen/idea-php-symfony2-plugin#2826

[fabpot]

See #4871

[upsun-dispatch]

📋 PR Summary

This PR adds an optional docs="..." metadata option to {% types %} entries and to the {% block %} tag. For types, docs is stored in the node mapping (defaulting to null and requiring =); for block, it is stored as a new optional docs attribute via a backward-compatible constructor argument, and is only treated as an option when followed by = so the shortcut {% block title docs %} still works. Documentation, CHANGELOG, and tests are added.

Changes

Layer / File(s)	Summary
changelog & docs
CHANGELOG	Adds a changelog entry for the new docs option on the types and block tags.
doc/tags/block.rst	Documents the docs option on the block tag with a versionadded note and example.
doc/tags/types.rst	Documents the docs option on types entries with a versionadded note and example.
node model
src/Node/BlockNode.php	Adds an optional ?string $docs constructor argument stored as a docs node attribute; BC preserved.
src/Node/TypesNode.php	Updates the mapping type docblock to include docs: string|null.
parsing
src/TokenParser/BlockTokenParser.php	Parses a docs="..." option after the block name, only when docs is followed by =, preserving the shortcut syntax.
src/TokenParser/TypesTokenParser.php	Parses an optional docs="..." option after each type string, requiring an equal sign, and stores it in the mapping.
tests
tests/TokenParser/BlockTokenParserTest.php	New test covering the docs option, defaulting to null, and shortcut-syntax compatibility.
tests/TokenParser/TypesTokenParserTest.php	Adds tests for the docs option, the required equal sign, and updates expected mapping shapes.

[upsun-dispatch]

🔵 Info — Duplicated, divergent option parsing across two tags raises future maintenance cost.

The docs option is parsed differently in the two tags: BlockTokenParser uses test()+look() and silently falls back to the shortcut body when docs is not followed by =, while TypesTokenParser uses nextIf()+expect() and raises The "docs" option must be followed by an equal sign (=). The divergent block behavior is required to preserve the {% block title docs %} shortcut, but the two implementations duplicate the option-detection logic with different error semantics, so a future change to the option (e.g. renaming docs to desc) must be made in two places kept manually in sync.

[fabpot]

Closing in favor of #4871
Thanks for the work you've done here, it helped me think about BC and I found another path without.