Minor doc fixes #476
Minor doc fixes #476
Conversation
theofidry
commented
Mar 19, 2016
theofidry
commented
| Q | A |
|---|---|
| Bug fix? | yes |
| New feature? | no |
| BC breaks? | no |
| Deprecations? | no |
| Tests pass? | yes |
| Fixed tickets | none |
| License | MIT |
| Doc PR | not required |
- Fix a PHPDoc return type comment - Add a missing return statement - Add a TODO comment
theofidry
force-pushed
the
minor-changes
branch
from
549830e
to
f9fad4e
Compare
| @@ -60,7 +60,7 @@ public function getType() | |||
| * | |||
| * @param Type $type | |||
| * | |||
| * @return self | |||
| * @return PropertyMetadata | |||
There was a problem hiding this comment.
using self here is misleading as it implies you are returning the same object, which is not the case.
There was a problem hiding this comment.
self is correct. You have $this in mind.
There was a problem hiding this comment.
self means an object of the same class, not the same instance.
There was a problem hiding this comment.
For me in this case (return value of the phpdoc), self and this would mean the exact same thing
There was a problem hiding this comment.
Those terms are defined in PSR-5 (still a draft): https://github.com/phpDocumentor/fig-standards/blob/b994d853b8ba33bd4bfb00e53cc268d57a5d1e7b/proposed/phpdoc.md#keyword
There was a problem hiding this comment.
But as you said it's still a draft, it might change. And as it's still a draft, and not very widespread, I'm more concern on how our library consumer may interpret it. Even if both are technically valid, I would rather pick the more intuitive one.
There was a problem hiding this comment.
Actually, it's here too FWIW: https://www.phpdoc.org/docs/latest/references/phpdoc/types.html
The PSR standard is still a draft, but as far as phpDocumentor (the library) is concerned, that's how it should be. And I don't think anyone would want to deviate from that without good reason (since I'd think it's also how IDEs etc. have implemented it)...
There was a problem hiding this comment.
I'd think it's also how IDEs etc.
Well, besides finding that unintuitive, IDE do not recognise it either (at least PhpStorm 2016.1)
But if you're finding it being more of an hassle that' fair, I just want to raise that point :)
There was a problem hiding this comment.
👎 to change this. self is perfectly valid according to the current and future PHPDoc standard. It also eases the refactoring and improves the readability.
|
Ok, so let's stick with |
