Simplify first line in constructor doc comments to "Constructor."

+1 on the issue, but -1 on the proposal: it states the obvious.

I'd rather

omit the first line comment.

as the alternative suggestion says.

Other projects just add extra annotations (including phpstan or psalm ones) for the parameters where it's relevant to add them.

omit the first line comment.

How do you want to handle constructors that need additional doc text as explanation?

E.g. Drupal\Component\Annotation\Plugin

class Plugin implements AnnotationInterface {
[..]
  /**
   * Constructs a Plugin object.
   *
   * Builds up the plugin definition and invokes the get() method for any
   * classed annotations that were used.
   */
  public function __construct($values) {

This would become

class Plugin implements AnnotationInterface {
[..]
  /**
   * Builds up the plugin definition and invokes the get() method for any
   * classed annotations that were used.
   */
  public function __construct($values) {

I used this regex to find examples:

/\*\*(
 *\* [^@].*|
 *\*){3}(
 *\* .*)*
 *\*/
 *public function __construct

In general, logic in constructors should be avoided.
But sometimes it can't, or it is already there and we can't remove it for BC reasons.

it states the obvious.

It is true.
But it also gives some visual orientation, if the actual method name is further below.
And it is easy to generate or just copy/paste.

Other projects just add extra annotations (including phpstan or psalm ones) for the parameters where it's relevant to add them.

Or they omit documentation, and then are super confusing to read.
(just to make the point that the grass is not always greener elsewhere)

As for the "extra annotations .. for the parameters", I assume you just mean regular old `@param` docs, just not for all parameters?
There are already issues talking about the option of an incomplete collection of param docs.

Imo we can still do the change proposed here and then further relax in future issues.

+1

Personally, I’ve been using “Constructs a new class instance.” as the first line, which still follows the “start with third-person verb” rule while also solving the listed problems. But I do see the appeal of making this even shorter to make it easier to spot, so would be fine changing it to “Constructor.” as well. If there was a vote, though, I’d go for “Constructs a new class instance.” – even though it’s a bit longer, it’s in line with the almost universal format for method doc comments and once you read “Constructs” you already know what’s going on.

Personally, I’ve been using “Constructs a new class instance.” as the first line, which still follows the “start with third-person verb” rule

even though it’s a bit longer, it’s in line with the almost universal format for method doc comments and once you read “Constructs” you already know what’s going on.

For me, magic methods and especially the constructor are special because you (typically) don't call them directly.
(For the constructor, an exception would be calling the parent class constructor.)

The "start with third-person verb" gives you a promise what you can expect by calling the method.
It would be justifiable if we decide to not do this on some or all magic methods.

I support #3.