Allow no description for "@return self"

Problem/Motivation

In #3129184: Remove description from @return $this pointed that core should not provide description for @return $this but that's not pointed in coding standards https://www.drupal.org/docs/develop/standards/api-documentation-and-comm...

Update coding standards about that case and introduce sniff #3326850: Warn if @return $this has description

The current sniff allows for no description of "@return $this" and "@return static".

Benefits

If we adopted this change, the Drupal Project would benefit by being more consistent.

Three supporters required

1. https://www.drupal.org/u/borisson_ (2025-02-11)
2. https://www.drupal.org/u/drunken-monkey (2025-02-15)
3. https://www.drupal.org/u/joachim (2025-02-18)

Proposed changes

Change documentation to explicitly allow no description for "@return $this", "@return self", and "@return static".
Change the relevant sniff to allow not no description for "@return self".

1. https://www.drupal.org/docs/develop/standards/php/api-documentation-and-comment-standards#types

Current text

Syntax notes:

• ...
• When you are returning the main class object ($this), use @return $this.
• When creating a new instance of the same class, use @return static.

Drupal standards notes:

• ...
• You may omit the description if using @return $this or @return static.

Proposed text

Syntax notes:

• ...
• When you are returning the main class object ($this), use @return $this.
• When creating a new instance of the same class, use @return static.
• When creating a new instance of the same class, and that class is final, use @return self.

Drupal standards notes:

• ...
• You may omit the description if using @return self, @return static, or @return $this.

2. Repeat the above for each page or sub-page that needs to be changed.

Remaining tasks

1. Create this issue in the Coding Standards queue, using the defined template
2. Add supporters
3. Create a Change Record
4. Review by the Coding Standards Committee
5. Coding Standards Committee takes action as required
6. Discussed by the Core Committer Committee, if it impacts Drupal Core
7. Final review by Coding Standards Committee
8. Documentation updates
   1. Edit all pages
   2. Publish change record
   3. Remove 'Needs documentation edits' tag
9. If applicable, create follow-up issues for PHPCS rules/sniffs changes

For a full explanation of these steps see the Coding Standards project page