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?

Answer 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.

Answer 2

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.