Documenting inherited functions/variables in subclasses with phpdoc

Question

Lets say I have parent class with some variable, which has phpdoc:

class Parent
{
    /**
     * This variable stores some important value that
     * is going to be changed in child classes
     * @var integer
     */
    public $variable = 0;
}

Now I am writing child class, which has this variable overriden:

class Child extends Parent
{
    public $variable = 10;
}

So my question is: what phpdoc should I write for $variable in Child class, so I do not have to copy and paste variable description? Same question goes for methods. Help is much appreciated.

Update: I've asked this question after I've seen errors after creating phpdoc, like "No summary for property $variable" in Child class. If I add this summary - error disappears, but phpdoc shows description from Parent class anyway, no matter what I write in Child class. What am I doing wrong?

{@inheritDoc} seems to be used for class description, not for variable/method. Maybe it should be done with {@see}, but I seem to be unable to find the correct way. — mr. Pavlikov
– mr. Pavlikov, Commented Jul 22, 2013 at 13:40
Ah yes, seems they changed it. Funny though, I know a major open source PHP project that uses {@inheritdoc} religiously on class methods/variables, not just for classes. And their docs compile just fine. In fact, even Symfony use it so it's definitely the right way to go — Clive
– Clive, Commented Jul 22, 2013 at 13:43

ashnazg · Accepted Answer · 2013-07-22 15:15:28Z

1

That behavior sounds like a bug to me. A complete lack of docblock on the child class property should result in the parent property docblock being inherited completely. Please report it as an issue at the github repo.

answered Jul 22, 2013 at 15:15

ashnazg

6,7282 gold badges34 silver badges40 bronze badges

Sign up to request clarification or add additional context in comments.

Comments

Arthur Eudeline · Accepted Answer · 2021-07-01 13:56:59Z

You can use @inheritdoc on class members such as consts, properties, methods, ... And they can be inherited from interfaces, parent classes, traits, ...

example :

interface MyInterface {
  
  /**
   * My doc
   *
   * @param string $myParam
   *
   * @return string|null
   */
  public function myMethodToImplement( string $myParam ) : ?string;
  
}

abstract class MyParentClass {
  
  /**
   * My inherited doc
   *
   * @param string $myParam
   *
   * @return string|null
   */
  public function myInheritedMethod( string $myParam ) : ?string {}
  
}


class MyClass extends MyParentClass implements MyInterface {
  
  /**
   * @inheritdoc
   */
  public function myInheritedMethod ( string $myParam ) : ?string {
    return parent::myInheritedMethod( $myParam );
  }
  
  
  /**
   * @inheritDoc
   *
   * @param bool $addedParam An added param
   *
   * You can add tags and still inherit from parent doc
   *
   * @throws NotImplementedException
   */
  public function myMethodToImplement ( string $myParam, bool $addedParam = false) : ?string {
    throw new NotImplementedException( __METHOD__ );
  }
}

With IDE such as PHPStorm, I have autocompletion working and quick documentation as well. If I Generate the documentation of this code with PHPDocumentor, Its works as well.

Collectives™ on Stack Overflow

Documenting inherited functions/variables in subclasses with phpdoc

2 Answers 2

Comments

Comments

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

Comments

Comments

Related