Skip to content

Introduce sniffs for docblocks #167

@jaymcp

Description

@jaymcp

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>
 */

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions