Discussion: @inheritDoc vs @return $this #1767
Replies: 14 comments
-
There is not much documentation about this .... from phpDocumentor ...
|
Beta Was this translation helpful? Give feedback.
-
Can we first agree that the behavior of PhpStorm should be the determining factor? |
Beta Was this translation helpful? Give feedback.
-
👍 from me, I would just add that it has to be understood by phpstan too. |
Beta Was this translation helpful? Give feedback.
-
We use VS Code + PHP exntensions, one of which
That covers it. |
Beta Was this translation helpful? Give feedback.
-
Of course. It was just for info, I dont use phpDoc, but it seems to be same as phpstorm works.
Yep. IDE improvements are nice to work with, but at the end I would like to have code/docs that passes static tests (phpstan, pslam, or whatever) |
Beta Was this translation helpful? Give feedback.
-
I think the case is fairly strong that where the class method is likely to be overridden and a method is likely to be used in chaining and returns the parent class method return value of the same name which happens to use I've proven that this is the only (or at least best to my knowledge) way for PhpStorm to correctly infer types and @tmotyl has confirmed that PhpStan is ok with this syntax so it seems to be the best solution to be compatible with both.
A good example would be https://github.com/OpenMage/magento-lts/pull/771/files#diff-957cf8fbbb2ba5e503830ce812d79f99R259 |
Beta Was this translation helpful? Give feedback.
-
Just a comment: I prefer following the standards, not a single implementation. |
Beta Was this translation helpful? Give feedback.
-
I tried Colin's code in VS Code, it chain for both methods: |
Beta Was this translation helpful? Give feedback.
-
@colinmollenhour what are your settings in phpstorm? Both methods work (no highlighting on I still use 2019.1 ... |
Beta Was this translation helpful? Give feedback.
-
As a workaround we could do sth like this in child class (for parent methods which returns ’$this’)
Sorry for formatting, im writing from mobile ;) |
Beta Was this translation helpful? Give feedback.
-
imho @inheritdoc is "human" readable and it works perfectly (?) with ide`s ... less code, less possible errors, works with phpdoc/phpdox ....
|
Beta Was this translation helpful? Give feedback.
-
for me inheritdoc is NOT human readable. I need to switch context to read the argument description. |
Beta Was this translation helpful? Give feedback.
-
You can see that one way or another. @inheritdoc tells me to look at the overridden method. This might be one step more, but how often is it needed? I think it is important that the IDE works, if necessary also tools like phpDocumentor or something similar works as well. The example should only show that you can save yourself duplicate documentation, especially if the original description is a bit longer. Instead of copying the DOCblock to child methods, which is not update safe, you could also use @inheritdoc. |
Beta Was this translation helpful? Give feedback.
-
Oops, my example was indeed flawed ( |
Beta Was this translation helpful? Give feedback.
-
Continuation of discussion from here: #783 (comment)
Beta Was this translation helpful? Give feedback.
All reactions