Coding standards discussion: #3060580: Allow inheritdoc and inheritDoc?

Problem: our Coding standards want lower case {@inheritdoc} but according to the PHPDoc spec it should be spelled with an uppercase "d" .

Action plan for now: allow both variants until the discussion is settled.

CommentFileSizeAuthor
#7 2939783-7.patch3.02 KBbr0ken

Comments

DamienMcKenna created an issue. See original summary.

borisson_’s picture

Let's also make sure that #2858021: fix {inheritdoc} typos is integrated in this issue as well, making sure that the @ sign is included.

damienmckenna’s picture

Issue summary: View changes

The PHPDoc spec says it should be spelled with an uppercase "d".

damienmckenna’s picture

Issue summary: View changes
klausi’s picture

Version: 8.x-2.x-dev » 8.x-3.x-dev
Issue summary: View changes
Issue tags: +DevDaysTransylvania

The problem is that our coding standards explicitly say we should write it with lower case d. There is a coding standards discussion at #3060580: Allow inheritdoc and inheritDoc? to maybe change that.

Until that is settled I think we should allow both variants in Coder.

br0ken’s picture

Assigned: Unassigned » br0ken
Issue tags: +DevDaysCluj
br0ken’s picture

Status: Active » Needs review
StatusFileSize
new3.02 KB
klausi’s picture

Status: Needs review » Needs work

Nice, thanks a lot! The approach is not perfect because now it would allow {@InHeRiTdOc}, right? That is a bit ugly, so better we check for the exact casing instead?

  1. +++ b/coder_sniffer/Drupal/Test/good/good.php
    @@ -1014,6 +1014,15 @@ class Foo implements FooInterface {
    +  /**
    +   * {@inheritDoc}
    +   *
    +   * Allow "inheritDoc".
    +   *
    +   * @link https://www.drupal.org/project/coder/issues/2939783
    +   */
    +  public function test4() {}
    

    I think this is not a good example because it allows aditional text in the comment. I think {@inheritDoc} should only be used standalone, if you need to modify the comment on a function then you should copy the content from the parent class to make it clear. I know we are not forbidding it in Coder yet, but we should not add more examples that do this.

    Can you replace this with just {@inheritDoc} and nothing else?

  2. +++ b/coder_sniffer/DrupalPractice/Test/good/good.php
    @@ -175,4 +175,9 @@ class StrictSchemaEnabled {
    +  /**
    +   * {@inheritDoc}
    +   */
    +  protected $allowCaseInsensitiveInheritDoc = TRUE;
    

    we should not modify the DrupalPractice standard with this change, so this example should also go into the Drupal standard good.php

Can you also file this as pull request against https://github.com/pfrenssen/coder ? Then we see the automated tests run.

rosinegrean’s picture

Issue tags: -DevDaysCluj

  • klausi committed 92c3c77 on 8.x-3.x authored by BR0kEN
    fix(DocComment): Allow inheritDoc with a capital D in doc comments (#...
klausi’s picture

Status: Needs work » Fixed

Updated the patch and committed it, thanks!

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.