Custom reference syntax to class or class member in comments make impossible to navigate in IDE
insperedia opened this issue · 19 comments
Hi,
I am one of Yii plugin developer for PHPStorm. And want to discuss one fundamental problem in Yii2.
The custom syntax for reference to class or class member in comments makes it impossible to implement navigation in IDE(PHPStorm). For example [[SomeClassName]]. The problem is that plugin can manipulate only DOM that is built by IDE parser. Because PHP plugin is not open source it is impossible to modify PHP parser to make this custom syntax work.
BUT as I remember IDE parses any string with @ in the beginning. So format can be like this, @link|ClassName::classMember, or something similar.
If there are resources to fix this I can help to find right format to make it possible to implement working links in PHPStorm plugin.
Hi @insperedia,
First of, a big thank you for this plugin which really makes our lives easier :)
I think @cebe may be your contact of choice for this issue, as he's maintaining yii2-apidoc & deals with the guide generation which relies on those links.
The reason why we did use our own markdown syntax for refering to classes and methods was that there is no clear defininiton in PHPdoc on how to handle these links:
https://docs.phpdoc.org/references/phpdoc/tags/link.html
Important The effects of the inline version of this tag are not yet fully implemented in PhpDocumentor2. There’s only URI support (i.e. no support for Structural Elements), and even that is available only in long descriptions.
I have not checked current situation, but "PSR-5: PHPDoc Standard" is in Draft since 2013, in its current state it does not provide much help for links like this.
In the original draft @link is only mentioned as "deprecated" and also specifed for URLs, not classes or methods/properties.
So unless we get a specification for how to parse @link tags that work the same accross different IDEs this issues is not easy to solve.
Here's current state: https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc-tags.md#56-link
Aha cool, did not know about PSR-19 :)
The URI MUST be complete and well-formed as specified in RFC 2396.
So we should propose to extend definition of @link to allow a FQSEN, like in @see:
https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc-tags.md#56-link
Actually, @link was just an example, not an actual proposition, and it was just accident it was the same as an existent tag. Fact is that plugin can read ANY @Whatsever and following text after space (this should be checked). Moreover, I see that @see probably fits the requirement, and it already works in IDE.
My main idea was that [[ClassRef]] does not work and it is impossible to make it interactive.
Yes. In PhpStorm the following works well:
See details in {@see \yii\helpers\StringHelper}.
Also check {@see \yii\helpers\StringHelper::dirname()}.
I think it's fine to switch to that syntax.
Please don't forget to update https://github.com/yiisoft/yii2-apidoc yii-apidoc accordingly 👍
There is no yii-apidoc ?
Not yet.
As I can see this syntax ({@see \yii\helpers\StringHelper}) is not recognized by PhpStorm if it's on the same line with @param:
/**
* Generates a link tag that refers to an external CSS file.
* @param array|string $url the URL of the external CSS file. This parameter will be processed by {@see Url::to()}.{@see Url::to()} is not interactive.
Likely it need FQN.
No, it doesn't work either.
{@see \yii\helpers\Url::to()}
Actually, only the first occurrence of the @see tag is not interactive, the next one becomes interactive again:
/**
* @param array|string $url the URL of the external CSS file. This parameter will be processed by {@see Url::doesNotWork()} {@see Url::works()}.
The same is with @return
* @return int {@see BaseIpHelper::IPV4} or {@see BaseIpHelper::IPV6}Closing. Mostly done.