Merge pull request #296 from phpDocumentor/fix/287-line-endings

Improve line-endings for windows.

examples/03-reconstituting-a-docblock.php

@@ -20,7 +20,7 @@ $factory  = DocBlockFactory::createInstance();
 $docblock = $factory->create($docComment);
 
 // Create the serializer that will reconstitute the DocBlock back to its original form.
-$serializer = new Serializer();
+$serializer = new Serializer(0, '', true, null, null, PHP_EOL);
 
 // Reconstitution is performed by the `getDocComment()` method.
 $reconstitutedDocComment = $serializer->getDocComment($docblock);

examples/04-adding-your-own-tag.php

@@ -126,5 +126,5 @@ $customTagObjects = $docblock->getTagsByName('my-tag');
 
 // As an experiment: let's reconstitute the DocBlock and observe that because we added a __toString() method
 // to the tag class that we can now also see it.
-$serializer              = new Serializer();
+$serializer              = new Serializer(0, '',true, null, null, PHP_EOL);
 $reconstitutedDocComment = $serializer->getDocComment($docblock);

src/DocBlock/DescriptionFactory.php

@@ -17,7 +17,6 @@ use phpDocumentor\Reflection\Types\Context as TypeContext;
 use phpDocumentor\Reflection\Utils;
 
 use function count;
-use function explode;
 use function implode;
 use function ltrim;
 use function min;
@@ -146,7 +145,7 @@ class DescriptionFactory
      */
     private function removeSuperfluousStartingWhitespace(string $contents): string
     {
-        $lines = explode("\n", $contents);
+        $lines = Utils::pregSplit("/\r\n?|\n/", $contents);
 
         // if there is only one line then we don't have lines with superfluous whitespace and
         // can use the contents as-is

src/DocBlock/Serializer.php

@@ -42,6 +42,8 @@ class Serializer
 
     /** @var Formatter A custom tag formatter. */
     protected $tagFormatter;
+    /** @var string */
+    private $lineEnding;
 
     /**
      * Create a Serializer instance.
@@ -51,19 +53,22 @@ class Serializer
      * @param bool      $indentFirstLine Whether to indent the first line.
      * @param int|null  $lineLength      The max length of a line or NULL to disable line wrapping.
      * @param Formatter $tagFormatter    A custom tag formatter, defaults to PassthroughFormatter.
+     * @param string    $lineEnding      Line ending used in the output, by default \n is used.
      */
     public function __construct(
         int $indent = 0,
         string $indentString = ' ',
         bool $indentFirstLine = true,
         ?int $lineLength = null,
-        ?Formatter $tagFormatter = null
+        ?Formatter $tagFormatter = null,
+        string $lineEnding = "\n"
     ) {
         $this->indent              = $indent;
         $this->indentString        = $indentString;
         $this->isFirstLineIndented = $indentFirstLine;
         $this->lineLength          = $lineLength;
         $this->tagFormatter        = $tagFormatter ?: new PassthroughFormatter();
+        $this->lineEnding = $lineEnding;
     }
 
     /**
@@ -96,7 +101,7 @@ class Serializer
 
         $comment = $this->addTagBlock($docblock, $wrapLength, $indent, $comment);
 
-        return $comment . $indent . ' */';
+        return str_replace("\n", $this->lineEnding, $comment . $indent . ' */');
     }
 
     private function removeTrailingSpaces(string $indent, string $text): string

src/DocBlock/Tag.php

@@ -21,7 +21,6 @@ interface Tag
 
     /**
      * @return Tag|mixed Class that implements Tag
-     *
      * @phpstan-return ?Tag
      */
     public static function create(string $body);

src/DocBlock/Tags/Method.php

@@ -59,7 +59,6 @@ final class Method extends BaseTag implements Factory\StaticMethod
 
     /**
      * @param array<int, array<string, Type|string>> $arguments
-     *
      * @phpstan-param array<int, array{name: string, type: Type}|string> $arguments
      */
     public function __construct(
@@ -186,7 +185,6 @@ final class Method extends BaseTag implements Factory\StaticMethod
 
     /**
      * @return array<int, array<string, Type|string>>
-     *
      * @phpstan-return array<int, array{name: string, type: Type}>
      */
     public function getArguments(): array
@@ -239,10 +237,9 @@ final class Method extends BaseTag implements Factory\StaticMethod
 
     /**
      * @param mixed[][]|string[] $arguments
+     * @phpstan-param array<int, array{name: string, type: Type}|string> $arguments
      *
      * @return mixed[][]
-     *
-     * @phpstan-param array<int, array{name: string, type: Type}|string> $arguments
      * @phpstan-return array<int, array{name: string, type: Type}>
      */
     private function filterArguments(array $arguments = []): array

src/Utils.php

@@ -14,8 +14,8 @@ declare(strict_types=1);
 namespace phpDocumentor\Reflection;
 
 use phpDocumentor\Reflection\Exception\PcreException;
-
 use Webmozart\Assert\Assert;
+
 use function preg_last_error;
 use function preg_split as php_preg_split;
 

tests/integration/InterpretingDocBlocksTest.php

@@ -79,7 +79,14 @@ DESCRIPTION;
         $this->assertInstanceOf(DocBlock::class, $docblock);
         $this->assertSame('This is an example of a summary.', $summary);
         $this->assertInstanceOf(Description::class, $description);
-        $this->assertSame($descriptionText, $description->render());
+        $this->assertSame(
+            str_replace(
+                PHP_EOL,
+                "\n",
+            $descriptionText
+            ),
+            $description->render()
+        );
         $this->assertEmpty($docblock->getTags());
     }
 
@@ -124,6 +131,9 @@ DESCRIPTION;
         include(__DIR__ . '/../../examples/playing-with-descriptions/02-escaping.php');
 
         $this->assertSame(
+            str_replace(
+                PHP_EOL,
+                "\n",
             <<<'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: }.
@@ -135,7 +145,7 @@ Here are example texts where you can see how they could be used in a real life s
 
 Do note that an {@internal inline tag that has an opening brace ({) does not break out}.
 DESCRIPTION
-            ,
+            ),
             $foundDescription
         );
     }

tests/unit/DocBlock/DescriptionFactoryTest.php

@@ -20,6 +20,10 @@ use phpDocumentor\Reflection\DocBlock\Tags\Link as LinkTag;
 use phpDocumentor\Reflection\Types\Context;
 use PHPUnit\Framework\TestCase;
 
+use function str_replace;
+
+use const PHP_EOL;
+
 /**
  * @coversDefaultClass \phpDocumentor\Reflection\DocBlock\DescriptionFactory
  * @covers ::<private>
@@ -192,7 +196,7 @@ DESCRIPTION;
 
         $description = $factory->create($descriptionText, new Context(''));
 
-        $this->assertSame($expectedDescription, $description->render());
+        $this->assertSame(str_replace(PHP_EOL, "\n", $expectedDescription), $description->render());
     }
 
     /**

tests/unit/DocBlock/SerializerTest.php

@@ -17,6 +17,10 @@ use Mockery as m;
 use phpDocumentor\Reflection\DocBlock;
 use PHPUnit\Framework\TestCase;
 
+use function str_replace;
+
+use const PHP_EOL;
+
 /**
  * @coversDefaultClass \phpDocumentor\Reflection\DocBlock\Serializer
  * @covers ::<private>
@@ -63,7 +67,7 @@ DOCCOMMENT;
             ]
         );
 
-        $this->assertSame($expected, $fixture->getDocComment($docBlock));
+        $this->assertSameString($expected, $fixture->getDocComment($docBlock));
     }
 
     /**
@@ -98,7 +102,7 @@ DOCCOMMENT;
             ]
         );
 
-        $this->assertSame($expected, $fixture->getDocComment($docBlock));
+        $this->assertSameString($expected, $fixture->getDocComment($docBlock));
     }
 
     /**
@@ -133,7 +137,7 @@ DOCCOMMENT;
             ]
         );
 
-        $this->assertSame($expected, $fixture->getDocComment($docBlock));
+        $this->assertSameString($expected, $fixture->getDocComment($docBlock));
     }
 
     /**
@@ -174,7 +178,7 @@ DOCCOMMENT;
             ]
         );
 
-        $this->assertSame($expected, $fixture->getDocComment($docBlock));
+        $this->assertSameString($expected, $fixture->getDocComment($docBlock));
     }
 
     /**
@@ -198,9 +202,16 @@ DOCCOMMENT_AFTER_REMOVE;
         $genericTag = new DocBlock\Tags\Generic('unknown-tag');
 
         $docBlock = new DocBlock('', null, [$genericTag]);
-        $this->assertSame($expected, $fixture->getDocComment($docBlock));
+        $this->assertSameString($expected, $fixture->getDocComment($docBlock));
 
         $docBlock->removeTag($genericTag);
-        $this->assertSame($expectedAfterRemove, $fixture->getDocComment($docBlock));
+        $this->assertSameString($expectedAfterRemove, $fixture->getDocComment($docBlock));
+    }
+
+    public function assertSameString(string $expected, string $actual): void
+    {
+        $expected = str_replace(PHP_EOL, "\n", $expected);
+
+        self::assertSame($expected, $actual);
     }
 }

tests/unit/DocBlock/StandardTagFactoryTest.php

@@ -462,7 +462,6 @@ class StandardTagFactoryTest extends TestCase
 
     /**
      * @return string[][]
-     *
      * @phpstan-return array<string, array<int, string>>
      */
     public function validTagProvider(): array
@@ -526,7 +525,6 @@ class StandardTagFactoryTest extends TestCase
 
     /**
      * @return string[][]
-     *
      * @phpstan-return list<array<int, string>>
      */
     public function invalidTagProvider(): array

tests/unit/DocBlockFactoryTest.php

@@ -23,6 +23,10 @@ use phpDocumentor\Reflection\Types\Context;
 use PHPUnit\Framework\TestCase;
 use ReflectionClass;
 
+use function str_replace;
+
+use const PHP_EOL;
+
 /**
  * @uses               \Webmozart\Assert\Assert
  * @uses               \phpDocumentor\Reflection\DocBlock
@@ -134,7 +138,7 @@ class DocBlockFactoryTest extends TestCase
         $docblock = $fixture->create($given);
 
         $this->assertSame($summary, $docblock->getSummary());
-        $this->assertEquals(new Description($description), $docblock->getDescription());
+        $this->assertEquals(new Description(str_replace(PHP_EOL, "\n", $description)), $docblock->getDescription());
     }
 
     /**
@@ -159,12 +163,7 @@ class DocBlockFactoryTest extends TestCase
  */
 DOCBLOCK;
 
-        $description = <<<DESCRIPTION
+        $description = "This is a multiline Description\nthat contains a code block.\n\n    See here: a CodeBlock";
-This is a multiline Description
-that contains a code block.
-
-    See here: a CodeBlock
-DESCRIPTION;
 
         $docblock = $fixture->create($given);
 
@@ -180,14 +179,9 @@ DESCRIPTION;
      */
     public function testTagsAreInterpretedUsingFactory(): void
     {
-        $tagString = <<<TAG
-@author Mike van Riel <me@mikevanriel.com> This is with
-  multiline description.
-TAG;
-
         $tag        = m::mock(Tag::class);
         $tagFactory = m::mock(TagFactory::class);
-        $tagFactory->shouldReceive('create')->with($tagString, m::type(Context::class))->andReturn($tag);
+        $tagFactory->shouldReceive('create')->with(m::any(), m::type(Context::class))->andReturn($tag);
 
         $fixture = new DocBlockFactory(new DescriptionFactory($tagFactory), $tagFactory);