Stripped tag description in v5.6.1 with phpdoc-parser v2 #408
Description
When using phpDocumentor/ReflectionDocBlock v5.6.1 together with phpstan/phpdoc-parser v2, the output of Serializer::getDocComment() changes unexpectedly compared to using the same version with phpstan/phpdoc-parser v1.
Expected behavior
The output of Serializer::getDocComment() should remain consistent between phpstan/phpdoc-parser v1 and v2.
Actual behavior
- Multiline tag descriptions with indentation and
@(even if indented by a single white space) get stripped at the first indentation unless the previous line starts with@and is not indented. - Indentation is removed in the tag descriptions.
Examples
Case 1: Basic indentation loss and truncation
use phpDocumentor\Reflection\DocBlockFactory;
use phpDocumentor\Reflection\DocBlock\Serializer;
$docComment = '/**
* A summary.
*
* Description line 1.
* Description line 2 with indentation.
*
* @param array $example {
* ParamTag description should be indented.
*
* @type string $element1 Description of element 1.
* @type string $element2 Description of element 2.
* }
*/';
$factory = DocBlockFactory::createInstance();
$docBlock = $factory->create($docComment);
$reconstitutedDocComment = (new Serializer())->getDocComment($docBlock);
echo $reconstitutedDocComment;
// output using
// - phpDocumentor/ReflectionDocBlock 5.5.1 + phpstan/phpdoc-parser 1.33.0 output
// - phpDocumentor/ReflectionDocBlock 5.6.0 + phpstan/phpdoc-parser 1.33.0 output
// - phpDocumentor/ReflectionDocBlock 5.6.1 + phpstan/phpdoc-parser 1.33.0 output
// - phpDocumentor/ReflectionDocBlock 5.6.0 + phpstan/phpdoc-parser 2.1.0 output
/**
* A summary.
*
* Description line 1.
* Description line 2 with indentation.
*
* @param array $example {
* ParamTag description should be indented.
*
* @type string $element1 Description of element 1.
* @type string $element2 Description of element 2.
* }
*/
// phpDocumentor/ReflectionDocBlock 5.6.1 + phpstan/phpdoc-parser 2.1.0 output
/**
* A summary.
*
* Description line 1.
* Description line 2 with indentation.
*
* @param array $example {
* ParamTag description should be indented.
*/Case 2: Previous line starts with @ and is not indented
$docComment = '/**
* A summary.
*
* @param array $example {
* ParamTag description should be indented.
*
* @type string $element1 Description of element 1.
* @type string $element2 Description of element 2.
* }
*/';
// phpDocumentor/ReflectionDocBlock 5.6.1 + phpstan/phpdoc-parser 2.1.0 output
/**
* A summary.
*
* @param array $example {
* ParamTag description.
* @type string $element1 Description of element 1.
* @type string $element2 Description of element 2.
* }
*/Case 3: Previous line does not start with @ and is indented
$docComment = '/**
* A summary.
*
* @param array $example {
* ParamTag description should be indented.
*
* type string $element1 Description of element 1.
* @type string $element2 Description of element 2.
* }
*/';
// phpDocumentor/ReflectionDocBlock 5.6.1 + phpstan/phpdoc-parser 2.1.0 output
/**
* A summary.
*
* @param array $example {
* ParamTag description should be indented.
*
* type string $element1 Description of element 1.
*/Case 4: Previous line does not start with @ and is not indented
$docComment = '/**
* A summary.
*
* @param array $example {
* ParamTag description should be indented.
*
* type string $element1 Description of element 1.
* @type string $element2 Description of element 2.
* }
*/';
// phpDocumentor/ReflectionDocBlock 5.6.1 + phpstan/phpdoc-parser 2.1.0 output
/**
* A summary.
*
* @param array $example {
* ParamTag description should be indented.
*
* type string $element1 Description of element 1.
*/Other comments
- Related: Release 5.4.0 does not add our phpstan tags #365 ?
- This issue likely does not appear in tests (see testRegressionWordpressDocblocks()) because
phpstan/phpdoc-parseris locked to version 1.33.0.