Closed ancpru closed 4 years ago
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
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] [
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.
When a tag body starts with a "[", an exception is raised:
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).