Update about @return $this

It’s documented a bit further down, under Indicating data types in documentation → . But yes, I also often struggle to find things in our documentation.

Update to new issue template

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

This is already in the docs. So that should be fine already? What do we need to do for this issue?

@borisson_, thanks for finding that sentence! I surely missed it.

So, the sentence is in the section "Indicating data types in documentation" which is the wrong place. It should be with the '@return'. I have updated the issue summary with the proposal. The difference is also to add @return self.

Testing with Drupal.Commenting.FunctionComment.MissingReturnComment enabled and "@return $this", and "@return static" pass without a comment but "@return self" fails with "Description for the @return value is missing".

Improving the issue summary

Updated title. I also changed the current and proposed text since the information is in a different section.

There is a TBA in the proposed text which needs to completed.

Filled in the when TBA,
return static is only useful because it can do late binding, which is really helpful when that class is extended by another one. However final classes cannot be extended, so they can use self instead.

Added a comma in the proposed text, but looks good otherwise.

+1

Setting to NW and tagging for a change record.