Mark @deprecated method usage & omit @return void
HI there,
I'm working with the PHPDoc documentation on method signatures, classes, etc.
In the official PHPDoc Tag list (find it here: http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.pkg.html), there is a @deprecated tag, which is quite useful, if you are working with some legacy code and refactor it.
I would love to see a feature, where the usage of an as @deprecated marked method/function/... is highlighted somehow (underline it or sth).
And the last one:
Is it possible to disable the automatical addition of "@return void"?
According to Wikipedia, it is not recommended: http://en.wikipedia.org/wiki/PHPDoc#Tags
Please sign in to leave a comment.
Hi Jannek,
It would be good indeed. But then you (PhpStorm) have to differentiate when to show this warning and when not to based on target PHP version (some functions become deprecated in PHP 5.3 and some earlier).
I think the easiest (or more logical) way of implementing this in general will be via Inspections functionality (similar to HTML deprecated tags inspection). But you as any other person (as well as members of JB team) may have dofferent opinion on this.
Please vote/watch/comment this ticket: http://youtrack.jetbrains.net/issue/WI-3327?projectKey=WI or create another one if that does not meet your requirements.
As for the second one -- no, you cannot turn it off somehow right now. PhpStorm is no longer adding "@return void" for constructor (see this ticket: http://youtrack.jetbrains.net/issue/WI-3204?projectKey=WI). You are welcome to create your own ticket for other scenarios: http://youtrack.jetbrains.net/issues/WI#newissue=yes
Hi Andriy,
no, PhpStorm doesn't have to differentiate when to show these warnings. My only concern is, that functions like this:
/**
* Does sth
* @deprecated
*/
function doSth ()
{
// ...
}
will be somehow marked as deprecated. It's like I'm defining the return type via @returns bool.
It's exactly the same mechanism. And just like in the hint the note about the return type appears, there should be some identifiers, that the used method is marked as deprecated (in the hint and maybe curly underlining).
Also it is possible to specifiy the target PHP version (like in Netbeans), so it is also possible to decide, which PHP internals are marked as deprecated and which are not.
But please differentiate between the own functions marked as @deprecated and the php internals. But both features would be nice. ;-)
Hi Jannik,
1) This ticket already implemented: http://youtrack.jetbrains.net/issue/WI-3327?projectKey=WI
It works by marking such functions/methods with @deprecated tag in PHPDoc comment. You can see this feature in action in latest EAP build (98.191 -- you can get it here: http://www.jetbrains.net/confluence/display/wi)
This feature can be turned ON / OFF via File | Settings | Inspections | PHP | General | Deprecated (by default it has Severity set as "Info" -- but you can change it to "Warning" (as I did for myself) if you need this to be more important)
Also -- have a look at File | Settings | Editor | Colors & Fonts | General | Deprecated symbol. By default such deprecated method will have strikeout style -- but you can configure it here.
2) I have submitted two more tickets for PHP 5.3.x deprecated functions (different ways of displaying deprecated status -- targeted for different PHP versions):
http://youtrack.jetbrains.net/issue/WI-3670?projectKey=WI
http://youtrack.jetbrains.net/issue/WI-3668?projectKey=WI
If you need different ways of displaying deprecation status -- please leave a comments for any of those tickets or create your own (which may be better as it will be treated as separate request: http://youtrack.jetbrains.net/issues/WI#newissue=yes)
P.S.
I'm not a JB dev -- just an ordinary end user of PhpStorm as you are.