Phpdocumentor: 3.0.0: inline @internal tag with single closing brace is shown in docs

[jrfnl]

Given the following piece of code in file src/issue-2440.php:

<?php
class Issue2440
{
    /**
     * Function with a inline dev notes.
     *
     * - This function should show in the docs like normal.
     * - The dev notes should not show in the docs.
     *
     * {@internal Dev note with single closing brace.}
     *
     * {@internal Dev note old-style, double closing brace.}}
     *
     * @return bool
     */
    function inlineInternal() {}
}

with the following config:

<?xml version="1.0" encoding="UTF-8" ?>
<phpdocumentor
    configVersion="3"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="https://www.phpdoc.org"
    xsi:noNamespaceSchemaLocation="https://docs.phpdoc.org/latest/phpdoc.xsd"
>
    <title>Demo</title>
    <version number="latest">
        <api format="php">
            <source dsn=".">
                <path>src</path>
            </source>
        </api>
    </version>
    <template name="default"/>
</phpdocumentor>

and considering the double closing brace comment style has been removed from PSR-19 18 months ago...

Expected behavior

I'd expect neither of the two inline {@internal ...} tags to show in the documentation.

Actual behavior

While the note with the double closing brace isn't shown, the one with the single closing brace is shown.

As found in project

• Direct link to the source code where the issue was found
• Direct link to the HTML source of the generated docs
• Output as seen online

Steps to reproduce the problem

1. Issue can be reproduced with the above code sample and config or via the linked project.
2. Run php -f /path/to/phpDocumentor/bin/phpdoc

Your environment

• Version used: phpDocumentor v3.0.x-dev@d15f2d6
• Install method: git clone
• PHP version: 7.4.6
• Operating system and version: Windows 7
• Link to your project: https://github.com/PHPCSStandards/PHPCSUtils/
• Link to output as committed: https://github.com/PHPCSStandards/PHPCSUtils/tree/develop/docs/phpdoc
• Link to output online: https://phpcsutils.com/phpdoc/

[mvriel]

This is probably an issue in the ReflectionDocBlock component. Tagged this as a bug so that it can be researched

[jaapio]

After investigating this, the cause seems to have two legs.
First, our ReflectionDocblock component doesn't handle the inline tags always correct. There are edge cases that are not covered as they should.
Second, the description is handled as a string in phpDocumentor itself which makes the handling of behavior like this more complex.

The latter is quite an easy fix which I will do soon. The first item is more complex since it requires us to improve the way we are handling the descriptions in ReflectionDocblock. Which is done by a single regex right now. But I think that needs to be changed to be able to handle all cases. Which makes me wonder if a regex is the best solution for this.
I will create an issue for that in ReflectionDocblock

[jrfnl]

@jaapio Thanks for investigating! Let me know if there is anything I can do or test.

[jaapio]

I have improved the way phpDocumentor deals with descriptions in general. It should now handle the @internal correctly. Remember that we still have an issue in our ReflectionDocblock component which doesn't work in all situations. A description of @internal containing } will break the handling. Which will result in an unexpected } in the rendered description.

Because I expect this to be out side scope of this issue I'm closing this one.

[jrfnl]

Thanks @jaapio for all your work on this. I'll have a play with the current version in the near future.