Documentation on retrieving the doc comment text

[Radiergummi]

I'm wondering how I'm supposed to retrieve the description from the doc comment; I'm well aware the text isn't very relevant for PhpStan, but as phpdoc-parser is kind of a general library, I would have expected some variant of $node->getText() or $node->getDescription().

For example, given the following comment:

/**
 * This is a title
 *
 * This is some multi-line text in
 * the comment, serving as description.
 *
 * @some-tag
 */

I'd expect a getter to retrieve the first four lines verbatim, or ideally separate getters for the summary (the first line) and the detailed description (the rest after the blank line below the summary).

From what I can infer from the source code, my only option right now is doing some variation of this:

$node = $parser->parse($tokens);
$textNodes = array_filter($node->children, fn(Node $node) => $node instanceof PhpDocTextNode));
$lines = array_map(fn(PhpDocTextNode $textNode) => $textNode->text, $textNodes);
$nonBlankLines = array_filter($lines);

$commentTextContent = implode(PHP_EOL, $nonBlankLines);
// or
$summary = array_shift($nonBlankLines);
$description = implode(PHP_EOL, $nonBlankLines);

...which to me feels like something the library should do. Or am I totally missing something?

[ondrejmirtes]

Text is represented with the PhpDocTextNode already used by your code: https://phpstan.github.io/phpdoc-parser/PHPStan.PhpDocParser.Ast.PhpDoc.PhpDocTextNode.html

phpdoc-parser is a low-level library. You can use it to suit your needs. For example, it also needs to represent text that would be between the nodes so something like $node->getDescription() doesn't make much sense.

Your code:

$textNodes = array_filter($node->children, fn(Node $node) => $node instanceof PhpDocTextNode));

for this PHPDoc:

/**
 * This is a title
 *
 * This is some multi-line text in
 * the comment, serving as description.
 *
 * @some-tag
 * 
 * between tags
 * 
 * @some-other-tag
 */

will also return "between tags". Which is something you might or might not want. That's why phpdoc-parser is a low-level library and you can decide exactly what you want for yourself.

[Radiergummi]

Sorry, I might have expressed myself badly; I know my code sample works, my question was rather whether adding additional getters to the node class to access the plain description as a string would be desirable for phpdoc-parser, as having a getDescription() feels like it would fit the scope of a phpdoc parsing library. There's also different getters for various tag types, so having an additional one for text nodes doesn't seem too foreign to me.
The parser constructor also has a $textBetweenTagsBelongsToDescription parameter, so that concern seems to have been addressed already.

I respect the decision to keep the public API lean, however, so thanks for the swift response anyway.

[ondrejmirtes]

that concern seems to have been addressed already.

These flags are similar to what PHPStan does with bleeding edge: https://phpstan.org/blog/what-is-bleeding-edge

They will be removed in phpdoc-parser 2.0 (and the code will behave as set to true) because it's the new and desired behaviour, but in 1.x context it'd be considered as a BC break.

[github-actions[bot]]

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.