bug #180 Highlight nested PHP comments (javiereguiluz, wouterj)

This PR was merged into the main branch.

Discussion
----------

Highlight nested PHP comments

Related to symfony/symfony-docs#20121

This PR adds a failing test that shows the issue. This is the output change that would make test pass:

```diff
-                ), [ // wait
-                <span class="hljs-number">5</span>
-                seconds before processing
+                ), [
+                <span class="hljs-comment">// wait 5 seconds before processing</span>
```

Commits
-------

af7ee47 Allow one line comments in argument list
8f09af6 Highlight nested PHP comments

Author: javiereguiluz

src/Templates/highlight.php/php.json

@@ -204,7 +204,15 @@
                             "_": "variable"
                         },
                         {
-                            "$ref": "#contains.10.contains.3.contains.2",
+                            "$ref": "#contains.3",
+                            "_": "comment"
+                        },
+                        {
+                            "$ref": "#contains.4",
+                            "_": "comment"
+                        },
+                        {
+                            "$ref": "#contains.5",
                             "_": "comment"
                         },
                         {
@@ -258,19 +266,8 @@
                             "_": "variable"
                         },
                         {
-                            "className": "comment",
-                            "begin": "/\\*",
-                            "end": "\\*/",
-                            "contains": [
-                                {
-                                    "$ref": "#contains.2.contains.0"
-                                },
-                                {
-                                    "className": "doctag",
-                                    "begin": "(?:TODO|FIXME|NOTE|BUG|XXX):",
-                                    "relevance": 0
-                                }
-                            ]
+                            "$ref": "#contains.5",
+                            "_": "comment"
                         },
                         {
                             "className": "string",

tests/IntegrationTest.php

@@ -298,6 +298,10 @@ public function parserUnitBlockProvider()
             'blockName' => 'code-blocks/php-attributes',
         ];
 
+        yield 'code-block-php-nested-comments' => [
+            'blockName' => 'code-blocks/php-nested-comments',
+        ];
+
         yield 'code-block-text' => [
             'blockName' => 'code-blocks/text',
         ];

tests/fixtures/expected/blocks/code-blocks/php-nested-comments.html

@@ -0,0 +1,72 @@
+<p>You can do that by adding a "stamp" to your message:</p>
+<div translate="no" data-loc="10" class="notranslate codeblock codeblock-length-md codeblock-php">
+    <div class="codeblock-scroll">
+        <pre class="codeblock-lines">1
+2
+3
+4
+5
+6
+7
+8
+9
+10</pre>
+        <pre class="codeblock-code">
+            <code>
+                <span class="hljs-keyword">use</span>
+                <span class="hljs-title">Symfony</span>
+                \
+                <span class="hljs-title">Component</span>
+                \
+                <span class="hljs-title">Messenger</span>
+                \
+                <span class="hljs-title">MessageBusInterface</span>
+                ;
+                <span class="hljs-keyword">use</span>
+                <span class="hljs-title">Symfony</span>
+                \
+                <span class="hljs-title">Component</span>
+                \
+                <span class="hljs-title">Messenger</span>
+                \
+                <span class="hljs-title">Stamp</span>
+                \
+                <span class="hljs-title">DelayStamp</span>
+                ;
+                <span class="hljs-keyword">public</span>
+                <span class="hljs-function">
+                    <span class="hljs-keyword">function</span>
+                    <span class="hljs-title">index</span>
+                    <span class="hljs-params">
+                        (MessageBusInterface
+                        <span class="hljs-variable">
+                            <span class="hljs-variable-other-marker">$</span>
+                            bus
+                        </span>
+                        )
+                    </span>
+                </span>
+                {
+                <span class="hljs-variable">
+                    <span class="hljs-variable-other-marker">$</span>
+                    bus
+                </span>
+                -&gt;
+                <span class="hljs-title invoke__">dispatch</span>
+                (
+                <span class="hljs-keyword">new</span>
+                <span class="hljs-title invoke__">SmsNotification</span>
+                (
+                <span class="hljs-string">'...'</span>
+                ), [
+                <span class="hljs-comment">// wait 5 seconds before processing</span>
+                <span class="hljs-keyword">new</span>
+                <span class="hljs-title invoke__">DelayStamp</span>
+                (
+                <span class="hljs-number">5000</span>
+                ), ]);
+}
+            </code>
+        </pre>
+    </div>
+</div>

tests/fixtures/source/blocks/code-blocks/php-nested-comments.rst

@@ -0,0 +1,12 @@
+You can do that by adding a "stamp" to your message::
+
+    use Symfony\Component\Messenger\MessageBusInterface;
+    use Symfony\Component\Messenger\Stamp\DelayStamp;
+
+    public function index(MessageBusInterface $bus)
+    {
+        $bus->dispatch(new SmsNotification('...'), [
+            // wait 5 seconds before processing
+            new DelayStamp(5000),
+        ]);
+    }