Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Introduce sniffs for docblocks #167

Open
jaymcp opened this issue Aug 21, 2024 · 0 comments
Open

Introduce sniffs for docblocks #167

jaymcp opened this issue Aug 21, 2024 · 0 comments
Labels
enhancement New feature or request

Comments

@jaymcp
Copy link
Member

jaymcp commented Aug 21, 2024

Is your feature request related to a problem? Please describe.
Currently, our PHPCS Standard does not include many rules for assisting developers in conforming to our docblock documentation standards. This makes it difficult for developers to adhere to it if they are less familiar with the standard, and puts the onus on peers to catch deviations during code review.

Describe the solution you'd like
We should introduce sniffs that prompt the developer when they deviate from our defined standards.

Additional context
Our docblocks should conform to this style (this may not be an exhaustive example):

/**
 * Short description of function/method
 *
 * A longer description that further details any
 * specifics about the function/method, or any
 * additional context that may be useful for the
 * reader to understand about it.
 *
 * @see {some_other_function()}
 * @link https://some-documentation.site/contextual-info.html
 *
 * @param int      $post_id     The post ID.
 * @param string   $post_status The post status.
 * @param \WP_Post $post        The post object.
 *
 * @throws \Exception when something specific goes wrong.
 * @throws \ValueError if something different goes wrong.
 *
 * @return array<int,\WP_Post>
 */
@jaymcp jaymcp added the enhancement New feature or request label Aug 21, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

1 participant