Write example on escaping values in a DocBlock

Author: mvriel

examples/playing-with-descriptions/02-escaping.php

@@ -0,0 +1,47 @@
+<?php
+
+require_once(__DIR__ . '/../../vendor/autoload.php');
+
+use phpDocumentor\Reflection\DocBlockFactory;
+
+$docComment = <<<DOCCOMMENT
+/**
+ * This is an example of a summary.
+ *
+ * You can escape the @-sign by surrounding it with braces, for example: {@}. And escape a closing brace within an
+ * inline tag by adding an opening brace in front of it like this: {}.
+ *
+ * Here are example texts where you can see how they could be used in a real life situation:
+ *
+ *     This is a text with an {@internal inline tag where a closing brace ({}) is shown}.
+ *     Or an {@internal inline tag with a literal {{@}link{} in it}.
+ *
+ * Do note that an {@internal inline tag that has an opening brace ({) does not break out}.
+ */
+DOCCOMMENT;
+
+$factory  = DocBlockFactory::createInstance();
+$docblock = $factory->create($docComment);
+
+// Escaping is automatic so this happens in the DescriptionFactory.
+$description = $docblock->getDescription();
+
+// This is the rendition that we will receive of the Description.
+$receivedDocComment = <<<DOCCOMMENT
+/**
+ * This is an example of a summary.
+ *
+ * You can escape the @-sign by surrounding it with braces, for example: {@}. And escape a closing brace within an
+ * inline tag by adding an opening brace in front of it like this: {}.
+ *
+ * Here are example texts where you can see how they could be used in a real life situation:
+ *
+ *     This is a text with an {@internal inline tag where a closing brace ({}) is shown}.
+ *     Or an {@internal inline tag with a literal {{@}link{} in it}.
+ *
+ * Do note that an {@internal inline tag that has an opening brace ({) does not break out}.
+ */
+DOCCOMMENT;
+
+// Render it using the default PassthroughFormatter
+$foundDescription = $description->render();

tests/integration/InterpretingDocBlocksTest.php

@@ -66,4 +66,32 @@ public function testInterpretingTags()
         $this->assertSame('\\' . StandardTagFactory::class, (string)$seeTag->getReference());
         $this->assertSame('', (string)$seeTag->getDescription());
     }
+
+    public function testDescriptionsCanEscapeAtSignsAndClosingBraces()
+    {
+        /**
+         * @var string      $docComment
+         * @var DocBlock    $docblock
+         * @var Description $description
+         * @var string      $receivedDocComment
+         * @var string      $foundDescription
+         */
+
+        include(__DIR__ . '/../../examples/playing-with-descriptions/02-escaping.php');
+        $this->assertSame(<<<'DESCRIPTION'
+You can escape the @-sign by surrounding it with braces, for example: @. And escape a closing brace within an
+inline tag by adding an opening brace in front of it like this: }.
+
+Here are example texts where you can see how they could be used in a real life situation:
+
+    This is a text with an {@internal inline tag where a closing brace (}) is shown}.
+    Or an {@internal inline tag with a literal {@link} in it}.
+
+Do note that an {@internal inline tag that has an opening brace ({) does not break out}.
+DESCRIPTION
+            ,
+            $foundDescription
+        )
+        ;
+    }
 }

tests/integration/ReconstitutingADocBlockTest.php

@@ -20,9 +20,9 @@
 /**
  * @coversNothing
  */
-class InterpretingDocBlocksTest extends \PHPUnit_Framework_TestCase
+class ReconstitutingADocBlockTest extends \PHPUnit_Framework_TestCase
 {
-    public function testInterpretingASimpleDocBlock()
+    public function testReconstituteADocBlock()
     {
         /**
          * @var string $docComment

tests/unit/DocBlock/DescriptionFactoryTest.php

@@ -121,7 +121,8 @@ public function testIfSuperfluousStartingSpacesAreRemoved()
   description that you commonly
   see with tags.
 
-      It does have a code sample
+      It does have a multiline code sample
+      that should align, no matter what
 
   All spaces superfluous spaces on the
   second and later lines should be
@@ -134,7 +135,8 @@ public function testIfSuperfluousStartingSpacesAreRemoved()
 description that you commonly
 see with tags.
 
-    It does have a code sample
+    It does have a multiline code sample
+    that should align, no matter what
 
 All spaces superfluous spaces on the
 second and later lines should be