magento / magento/magento-coding-standard
Require @see annotations for plugin classes and methods
Nobody has claimed this yet.
- Dominant language
- PHP
- Stars
- 375
- Forks
- 165
- PR merge metrics
- No merged PRs in 30d
Description
### Rule
* A plugin class should have a `@see` annotation to the class(es) that it is intercepting.
* Each plugin method should have a `@see` annotation to the method(s) it is intercepting
### Reason
This rule would improve QOL for developers by providing a definitive link to what a plugin is intercepting. This can be especially useful for plugins that are intercepting more than one class.
### Implementation
An implementation has been written by Mediotype and can be modified for this standard. Our implementation checks:
* The rule checks only a class that has a namespace like `Vendor\Module\Model\Plugin\*` or `Vendor\Module\Plugin\*`
* The rule verifies that such a class has a class-level docblock containing a `@see` tag
* The rule checks only methods that are public and begin with before, after, or around (case sensitive)
* The rule verifies that such methods have a method-level docblock containing a `@see` tag
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 locating the existing PHP coding-standard rule implementations and their tests; the issue does not name specific files or entry points. Use the stated plugin namespace, class-level and method-level docblock conditions, then add coverage showing that qualifying plugin classes and before/after/around methods require @see annotations.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php
- Domain
- tooling
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 48/100