WordPress / WordPress/WordPress-Coding-Standards
Exception documentation - clarify use of @throws
Nobody has claimed this yet.
- Dominant language
- PHP
- Stars
- 2.8k
- Forks
- 521
- Avg merge
- 5d 20h
- Merged PRs (30d)
- 1
Description
Is your feature request related to a problem?
Currently, using the @throws annotation in the natural way (@throws \RuntimeException if $file could not be deleted. raises an Squiz.Commenting.FunctionComment.ThrowsNotCapital error. However, I haven't found any specific mention of @throws in the WordPress PHP documentation standard (it is mentioned briefly in the JavaScript documentation standard, but not with a usage example).
Describe the solution you'd like
There should be a standard for using @throws. I'd prefer if it allows @throws <Exception> <condition>, but really any explicit rule (and a corresponding sniff) would be OK. (At the moment, there's an upstream sniff, but no rule.)
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the WordPress PHP documentation standard and the existing upstream @throws sniff mentioned in the issue. Define the permitted @throws form and document it, then ensure the corresponding sniff enforces the chosen rule; no specific files or tests are named in the issue.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100