The way Stripe classes are architectured, there is no way an IDE can understand what class each method returns, which creates inspection issues in our code base.
This PR adds correct documentation to the following methods in Stripe_Charge:
I'll be happy to do more work on this project if you're willing to merge my pull requests.
Added documentation on Stripe_Charge methods.
Hi guys, are you following your pull requests?
Sorry for the delay, @BenMorel! I'll be happy to merge in PRs along these lines.
That's great news, @michelle, thank you!
Could you please merge this one first, and I'll open separate PR for the others?
@michelle Proper documentation is not clutter. All modern PHP libraries properly document their code with parameter types and return types, this is just standard practice. This is really important and I hope Stripe, as a payment gateway for developers, is aware of this!
As it stands, we're using more than 10 open-source libraries in our PHP application. Stripe is the only one that generates false positive inspection reports, and distracting our eye from real issues when developing, because the IDE is unable to determine the dynamic return types without explicit documentation from the library authors.
Sorry about that; I guess I wanted to do more research before merging in bits and pieces, which I do consider to be confusing. Happy to take a day next week to work on this and have standardized PHPdoc-style documentation in the entire codebase. I'll CC you on the PR :).
Great thank you, looking forward to it!
Let me know if this helps!
@michelle It does help, thanks! Now the IDE's type inference works fine.
There is still room for improvement with the dynamic properties using the __get() magic method, though, that could be explicitly documented on the class itself, for example:
* @property bool $paid
* @property bool $captured
* @property bool $refunded
This allows the IDE's inspection features to properly understand the properties as if they were actual Stripe_Charge class properties, and avoid warnings.
More information about @property can be found here.
Should I open a new issue for this feature request?
Sure, new issue would be nice to track.