Fix PHPDoc issues reported by PHPStan

[daledupreez]

Fixes STRIPE-<linear_issue_id>
Fixes #<github_issue_id>

Changes proposed in this Pull Request:

This PR updates the PHPDoc for large sections of our codebase to address issues reported by PHPStan, both to make it clearer what the expected behaviour is, and to make it easier to flag incorrect usage in the plugin.

Warning

I used multiple agents to iteratively get to this point, so I still need to review the full set of changes myself. We may need to split this PR into multiple smaller PRs so we can continue to make progress.

Testing instructions

---

• Covered with tests (or have a good reason not to test in description ☝️)
• Tested on mobile (or does not apply)

Changelog entry

• This Pull Request does not require a changelog entry. (Comment required below)

Changelog Entry Comment

Comment

Post merge

• Added testing instructions to the Release Testing Instructions wiki page (or does not apply)
• Added the needs docs label (or does not apply)
• Included this PR in the Release Thread scope (or does not apply)