Allow inheritdoc and inheritDoc?

phpDocumentor 1.x was using the {@inheritdoc} while 2.x uses {@inheritDoc}.

- 2.x: https://docs.phpdoc.org/guides/inheritance.html
- 1.x: https://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutori...

However, {@inheritDoc} (wrapped within brackets) means that only parent description is imported. Example:

class A {
  /**
   * Summary 1.
   *
   * Method's description.
   */
  public function myMethod() {}
}

class B extends A {
  /**
   * Summary 2.
   *
   * {@inheritDoc} It can be extended.
   */
  public function myMethod() {
    parent::myMethod();
  }
}

The resulting description for B::myMethod() will be Method's description. It can be extended.. This means we shouldn't use something like this:

class B extends A {
  /**
   * {@inheritDoc}
   */
  public function myMethod() {
    parent::myMethod();
  }
}

In my understanding, we should start writing @inhertiDoc without brackets.

Quoting https://docs.phpdoc.org/guides/inheritance.html.

Currently some applications have DocBlocks containing just the {@inheritDoc} inline tag to indicate that their complete contents should be inherited. This usage breaks with the PHPDoc Standard as summaries cannot contain inline tags and inheritance is automatic; you do not need to define a special tag for it.
However, it does make clear that an element has been explicitly documented (and thus not forgotten). As such we are working to include a new (normal) tag in the PHPDoc Standard @inheritDoc that will serve that purpose.

See also this issue, which has more about what people want vs. what we are doing vs. what PHPDoc and other documentation things do with @inheritdoc and similar tags:
#1994890: Allow {@inheritdoc} and additional documentation

Also please note that the Drupal project is *not* using PHPDoc standards.

I also find this a bit annoying, but not a lot, and I think I’d find seeing both variants mixed even more annoying.
Changing completely to {@inheritDoc} (instead of allowing both) seems to be completely out of the question, due to the sheer volume of completely unnecessary changes to our entire code base (Core plus nearly all contrib modules).
So, while I sympathize, I think I’m more leaning in the -1 direction.

We will allow both variants in Coder until this issue is settled. Popular IDEs such as PHPStorm are now pushing {@inheritDoc} in their autocomplete. That becomes very annoying for developers to fix that back to lower case d just to satisfy Coder.

That becomes very annoying for developers to fix that back to lower case d just to satisfy Coder.

I agree, this has been really annoying.

Changing completely to {@inheritDoc} (instead of allowing both) seems to be completely out of the question, due to the sheer volume of completely unnecessary changes to our entire code base (Core plus nearly all contrib modules).

I disagree, it's simple to automate and a lot easier to review compared to something like the array syntax conversion.

I would be +1 to completely change to the new notation.

I disagree, it's simple to automate and a lot easier to review compared to something like the array syntax conversion.

Easy to review, yes, but would still surely cause a lot of merge conflicts/necessitate patch re-rolls. (Or maybe not that many? Not sure how near to each other two changes must be to cause a conflict.)
But yes, “completely out of the question” was probably a bit too strong. In any case, this seems like something that would have to be evaluated and decided by a Core committer (or product manager or whatever role is appropriate here).

I would also +1 to change to the new notation.

But I do not like the IDE to enforce the new notation without making it configurable per project. There is an issue for PhpStorm related to this issue: https://youtrack.jetbrains.com/issue/WI-46482

PhpStan adopted both https://github.com/phpstan/phpstan/pull/2054

Here's a concrete example of when a patch ended up with a mixture of the two and failed code review in order to have all lowercase:

https://www.drupal.org/project/drupal/issues/3126957#comment-13563516

Any updates on this? It seems that both passes the validation currently, but it is honestly ugly to have two allowed styles.

I wouldn't mind which one would be the allowed one, I could argue for both.

Also I've to mention that even by changing to newer syntax, the work required for the old codebase is next to nothing.

FWIW, Symfony has abandoned the usage of @inheritdoc in 6.2,

It looks like this PHP Doc is useless

See https://github.com/symfony/symfony/pull/47390

@eiriksm, thanks for bringing this up.

As of 10.1.x, there is a sniff that standardizes on {@inheritdoc}, It was added in the related issue. This is in accord with existing policy. See {@inheritdoc}: Documentation inheritance.

I am changing this to Fixed. If I have missed something, re-open and explain what more there is to do.