For an abstract function, should the phpdoc be defined for the abstract function, the implemented function, or both?

Question

Is there a correct or standard way to do this?

For example:

AbstractFoo.php:

abstract class AbstractFoo {
    /**
     * Does the phpdoc go here?
     */
    public function fooFunction();
}

Foo.php:

class Foo extends AbstractFoo {
    /**
     * Or does the phpdoc go here?
     */
    public function fooFunction(){
        // some implementation
    }
}

Consider the following issues:

• If you put the phpdoc in the abstract FooFunction(), and control + click $foo->FooFunction(), you will end up at the Foo class' FooFunction(), which is undocumented, and not immediately obvious that it's implementing an abstract function. And if it was obvious, there's no easy way to get to the phpdoc in the abstract function, without

  • Determining what class the object was
  • Locating the abstract class it is inheriting
  • Doing a "find" on the function name in that abstract class

• If you put the phpdoc only in the children functions, then you're faced with duplicating phpdocs across the children functions of n number of inheriting classes.

• If you put the phpdoc in both, the abstract function's phpdoc becomes purposeless, unless a child class did not have a phpdoc, wanting to inherit the abstract's phpdoc. But even in this case, again, there's no easy way to navigate to that abstract phpdoc.

Answer 1

You should document an interface or abstract implementation. Otherwise, use @inheritdoc/document your implementation of an interface method.