Add a PHPCS rule to enforce full stops in PHPDoc comments

[abdelmalekkkkk]

Feature Description

Currently, our JS ESLint rules enforce full stops in JSDoc comments. To maintain consistency across the codebase (and save time during code reviews), we need to add a new PHPCS rule to enforce full stops in PHPDoc comments as well.

---

Do not alter or remove anything below. The following sections will be managed by moderators only.

Acceptance criteria

• A PHPCS linting rule is added to enforce a full stop (.) at the end of PHPDoc summary lines.
• Any existing PHP files that violate this rule are updated to conform, ensuring no linting errors are raised after applying the rule.

Implementation Brief

Since this convention has mostly been followed so far, there shouldn’t be many files affected by the new rule. Therefore, addressing it within this issue shouldn’t add significant effort so that opening a follow-up and commenting on those files separately would be needed.

Note: Refer to this POC PR for implementation.

• Add a custom PHPCS sniff for enforcing full stops in docblocks and inline comments.
  • Create the file at packages/phpcs-standards/SiteKit/Sniffs/Commenting/DocCommentFullStopSniff.php.
  • Implement the sniff to:
    • Register tokens for classes, interfaces, traits, functions, properties, constants, and inline comments.
    • For PHPDoc blocks:
      • Detect the summary section before a blank line or @tag.
      • Check only the last non-empty line of the summary.
      • Add a fixable error if punctuation (., !, or ?) is missing.
    • For inline // comment blocks:
      • Detect contiguous // lines as a single block.
      • Only process the first line of the block.
      • Check the last non-empty line in the block for the required punctuation.
      • Skip annotation-like comments (e.g., @todo, @phpcs).
      • Provide an auto-fix by appending a period.
• Update phpcs.xml to include the new rule.
  • Add <rule ref="SiteKit.Commenting.DocCommentFullStop"/> under the custom rules section.
• Run the lint-fix command to update the files that do not conform to the given rule.
  • Update these files in the PR.

Test coverage

No tests required.

QA Brief

Changelog entry

[eugene-manuilov]

AC ✔️