Keep paragraphs apart in ApiGen descriptions

phpdoc-parser puts each paragraph of a PHPDoc into its own text node.
ApiGen dropped the empty nodes between them and joined the rest with a
space, so every description rendered as one paragraph. Lists, tables and
code fences that did not start the description were not recognized, and
short descriptions in namespace listings showed the whole text.

Amp-Thread-ID: https://ampcode.com/threads/T-01a176c6-528a-7430-b296-e66930d153b4

Author: ondrejmirtes

apigen/apigen.neon

@@ -9,5 +9,8 @@ services:
 	renderer.filter:
 		factory: PHPStan\ApiGen\RendererFilter
 
+	analyze.phpDocResolver:
+		factory: PHPStan\ApiGen\PhpDocResolver
+
 	commonMark:
 		factory: PHPStan\ApiGen\MarkdownConverter

apigen/src/MarkdownConverter.php

@@ -7,8 +7,10 @@
 use League\CommonMark\Extension\CommonMark\Node\Inline\HtmlInline;
 use League\CommonMark\Extension\GithubFlavoredMarkdownExtension;
 use League\CommonMark\MarkdownConverter as BaseMarkdownConverter;
+use League\CommonMark\Output\RenderedContentInterface;
+use function str_replace;
 
-/** GitHub-flavored Markdown converter that escapes generic types written in PHPDoc descriptions. */
+/** GitHub-flavored Markdown converter for PHPDoc descriptions that escapes generic types and keeps paragraphs apart. */
 final class MarkdownConverter extends BaseMarkdownConverter
 {
 
@@ -22,4 +24,11 @@ public function __construct()
 		parent::__construct($environment);
 	}
 
+	public function convert(string $input): RenderedContentInterface
+	{
+		// ApiGen joins description nodes with a space, which would indent the paragraph
+		// after each separator and break code fences that start it.
+		return parent::convert(str_replace(' ' . PhpDocResolver::PARAGRAPH_SEPARATOR . ' ', PhpDocResolver::PARAGRAPH_SEPARATOR, $input));
+	}
+
 }

apigen/src/PhpDocResolver.php

@@ -0,0 +1,35 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\ApiGen;
+
+use ApiGen\Analyzer\NodeVisitors\PhpDocResolver as BasePhpDocResolver;
+use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocNode;
+use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocTextNode;
+use function array_merge;
+
+/**
+ * phpdoc-parser puts each paragraph into its own text node with an empty text node
+ * between them. ApiGen drops the empty nodes, which merges all paragraphs into one,
+ * so they are kept as blank lines here.
+ */
+final class PhpDocResolver extends BasePhpDocResolver
+{
+
+	public const PARAGRAPH_SEPARATOR = "\n\n";
+
+	protected function resolvePhpDoc(PhpDocNode $phpDoc): PhpDocNode
+	{
+		$children = [];
+		foreach ($phpDoc->children as $child) {
+			if ($child instanceof PhpDocTextNode && $child->text === '') {
+				$children[] = new PhpDocTextNode(self::PARAGRAPH_SEPARATOR);
+				continue;
+			}
+
+			$children = array_merge($children, parent::resolvePhpDoc(new PhpDocNode([$child]))->children);
+		}
+
+		return new PhpDocNode($children);
+	}
+
+}