Inline tags cause processing of subsequent tags to be discarded

[andrewnicols]

We have some (mostly legacy) code which makes use of inline PHPDoc tags within other tags, for example the @copyright line in the following example contains an inline @link tag:

/**
 * Unit tests for stored_progress_bar_cleanup
 *
 * @package   core
 * @copyright 2024 onwards Catalyst IT EU {@link https://catalyst-eu.net}
 * @author    Mark Johnson <mark.johnson@catalyst-eu.net>
 * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 * @covers    \core\task\stored_progress_bar_cleanup_task
 */

When Rector's BetterDocsParser processes this using phpstan\phpdoc-parser I'm seeing that the processing stops at the @copyright line just before the inline tag.

From a quick dive into the code it looks like this may be an issue with \PHPStan\PhpDocParser\Parser\PhpDocParser::parseOptionalDescriptionAfterDoctrineTag, which correctly identifies the @link tag, but because it is a Ast\PhpDoc\GenericTagValueNode, it stops processing the rest of the docblock tags any further.

phpdoc-parser/src/Parser/PhpDocParser.php

Lines 255 to 262 in 04c8de0

	if ($child instanceof Ast\PhpDoc\PhpDocTagNode) {
	if (
	$child->value instanceof Ast\PhpDoc\GenericTagValueNode
	|| $child->value instanceof Doctrine\DoctrineTagValueNode
	) {
	$tokens->rollback();
	break;
	}

As a result the only tags returned are:

 @package  => "core"
 @copyright => "2024 onwards Catalyst IT EU "

Given there is no authoritative PHPDoc reference it's hard to determine what the correct behaviour is here.

The phpDocumentor manual states that the inline {@link} tag is to:

Display a link to a URL, or link to an element's documentation in the the flow of descriptive text
https://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.inlinelink.pkg.html

The FIG proposal does not provide any guidance that I can see on the use of inline tags, beyond that fact that they exist and that @link is a valid inline tag.
https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc-tags.md

However the format of the copyright tag is a bit uncertain.

The phpDocumentor manual states that it is used unaltered:

phpDocumentor will display the copyright string unaltered.
https://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.copyright.pkg.html

The FIG proposal states that the coding style is up to the indvidual project:

The format of the description is governed by the coding standard of each individual project. It is RECOMMENDED to mention the year or years which are covered by this copyright and the organization involved.
https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc-tags.md#53-copyright

The same statement is also used in phpdoc:
https://docs.phpdoc.org/guide/references/phpdoc/tags/copyright.html

Given all of the above, I would argue that the parsing of these tags in phpdoc-parser is incorrect and that they should either:

• be treated as an inline tag which does not cause the parser to break at this point; or
• be treated as text and not as an inline tag at all (per the claims of phpDocumentor using the value unaltered for a copyright).

[ondrejmirtes]

I just added a test and in the AST it appears exactly how I'd expect it to (as description in GenericTagValueNode or DoctrineTagValueNode): 7adaab7

So if you're having issues with this, they're probably in Rector.

[github-actions]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.