Exception in StandardTagFactory

[ancpru]

When a tag body starts with a "[", an exception is raised:

   public function create(string $tagLine, ?TypeContext $context = null): ?Tag
    {
        if (! $context) {
            $context = new TypeContext('');
        }

        [$tagName, $tagBody] = $this->extractTagParts($tagLine);

        if ($tagBody !== '' && $tagBody[0] === '[') {
            throw new \InvalidArgumentException(
                'The tag "' . $tagLine . '" does not seem to be wellformed, please check it for errors'
            );
        }

        return $this->createTag($tagBody, $tagName, $context);
    }

Is there a reason for that?

We try to use some kind of markdown syntax in our project and the parser failes on a tag like "@see xxx"

Is there a description somewhere where to hook in to do some pre-processing? In the new version many things are declared final and it looks quite difficult to extend (or I just have not found the right place to hook in).

[jaapio]

I added that check because a [ as first character in a tag body seems to be invalid. I don't remember any more in which context this was the case. But it was something with annotations. The tag body doesn't have any relation with the error you are describing in @see xxx.

Please provide an example of the situation the parsing fails. So we can investigate what is going on

[ancpru]

I added that check because a [ as first character in a tag body seems to be invalid. I don't remember any more in which context this was the case. But it was something with annotations. The tag body doesn't have any relation with the error you are describing in @see xxx.

Please provide an example of the situation the parsing fails. So we can investigate what is going on

Well, I am at work to port the yii2-apidoc to the new reflection version. apidoc uses markdown and the yii-source contains tags like

@see [\This\Is\My\Class] or
@see [theOtherMethod()]

Thus factory gets a string starting with "["

It might make sense to change the format in the yii source as the @see syntax is now defined as "@see [URI | FQSEN] []", but I try to stay compatible with existing source.

Edit:

The examples above are not the real problem. These references are already in the standard format as they should be:

@see \This\Is\My\Class
or
@see theOtherMethod()

But there are a few cases like:

 * @see [hash_algos()](https://secure.php.net/manual/en/function.hash-algos.php)

The current yii2-apidoc can just handle both formats. May be I find a workaround for it by crating a custom factory, parsing it and turn such lines into the standard format internally.

Edit:

And I think it has to do with the tag body: I mean the check happens exactly here, on the tagBody:

if ($tagBody !== '' && $tagBody[0] === '[') {

This means, that it's not possible to create some custom tags which may begin with a "[" ...:

@mytag [blah]

I worked around the problem now by creating a own TagFactory which prefixes the tagBody with some gargabe if it starts with "[], then calls the standard TagFactory to create the stuff. This a bit dirty trick was necessary because createTag($tagBody, $tagName, $context) is private.

Note: I understand the now trendy pattern to close things (a lot of final, a lot of private) from the library developer POV. Everything not closed will be used to hook in and it's difficult to maintain a library and take care not to break extended classes.
But: This pattern is finally a extension nitemare where people end up in a lot of copy&paste-code or writing factories which wrap the standard implementation and so on.
The problem is: This pattern is great to use the library just as is. But it's very difficult to use in the sense of extending it's functionality.