Stripped tag description in v5.6.1 with phpdoc-parser v2

[IanDelMar]

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-parser is locked to version 1.33.0.

[jaapio]

This issue has been fixed in #409

[IanDelMar]

Great! Thank you!

[jaapio]

Thank you for reporting :-)