diff --git a/examples/playing-with-descriptions/02-escaping.php b/examples/playing-with-descriptions/02-escaping.php new file mode 100644 index 0000000..5ec772f --- /dev/null +++ b/examples/playing-with-descriptions/02-escaping.php @@ -0,0 +1,47 @@ +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 = <<render(); diff --git a/tests/integration/InterpretingDocBlocksTest.php b/tests/integration/InterpretingDocBlocksTest.php index e9664f0..91b8eb3 100644 --- a/tests/integration/InterpretingDocBlocksTest.php +++ b/tests/integration/InterpretingDocBlocksTest.php @@ -66,4 +66,32 @@ DESCRIPTION; $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 + ) + ; + } } diff --git a/tests/integration/ReconstitutingADocBlockTest.php b/tests/integration/ReconstitutingADocBlockTest.php index 3179645..92ac22e 100644 --- a/tests/integration/ReconstitutingADocBlockTest.php +++ b/tests/integration/ReconstitutingADocBlockTest.php @@ -20,9 +20,9 @@ use phpDocumentor\Reflection\DocBlock\Tags\See; /** * @coversNothing */ -class InterpretingDocBlocksTest extends \PHPUnit_Framework_TestCase +class ReconstitutingADocBlockTest extends \PHPUnit_Framework_TestCase { - public function testInterpretingASimpleDocBlock() + public function testReconstituteADocBlock() { /** * @var string $docComment diff --git a/tests/unit/DocBlock/DescriptionFactoryTest.php b/tests/unit/DocBlock/DescriptionFactoryTest.php index 2189144..d3043f9 100644 --- a/tests/unit/DocBlock/DescriptionFactoryTest.php +++ b/tests/unit/DocBlock/DescriptionFactoryTest.php @@ -121,7 +121,8 @@ This is a multiline 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 @@ This is a multiline 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