Best practice for PHP interfaces: should I document only the interface? [closed]

Question

I'm trying to standardize documentation for PHP interfaces. Is the best practice to maintain the method header only in the interface? For example, for this interface:

interface FooInterface {

    /** 
     * This will test the system in some special way
     * @param string $sName
     * @param integer $iCount
     * @return void
     */
    public function testMe ($sName, $iCount);
}

I would skip the method header documentation in the implementation:

class Foo implements FooInterface {

    /**
     * @see FooInterface::testMe
     */
    public function testMe ($sName, $iCount) {
        // implementation here
    }
}

Or is it better to document the parameters in both the interface and implementation? E.g.

class Foo implements FooInterface {

    /**
     * @see FooInterface::testMe
     * @param string $sName
     * @param integer $iCount
     * @return void
     */
    public function testMe ($sName, $iCount) {
        // implementation here
    }
}

Normally I prefer to minimize duplication and maintenance, but perhaps there are good reasons to store the header documentation for parameters and return values in both places?

Answer 1

When using phpDocumentor, the @inheritdoc annotation is a good idea, as already suggested by @Scalable. This (fixed) bug tracker issue confirms that the @inheritdoc annotations also works for implemented interfaces.

---

To expand on that a little bit:

Usually, a method comment should describe what a method does[1]. Typically, all implementations of a method defined by an interface should do the same (and only differ in their implementation). This in mind, I'd recomment the following:

1. use the method comment in the interface definition to describe what the method is supposed to do:

   interface UserRepository {
       /**
        * Returns all existing users (duh! usually, you'd omit a comment 
        * like this because the method signature is already self-explanatory).
        *
        * @return User[]
        */
       public function findAllUsers();
   }
   

2. use the @inheritdoc annotation in method comment in the implementing classes and provide additional implementation-specific details when necessary:

   class RemoteUserRepository implements UserRepository{
       /**
        * {@inheritdoc}
        *
        * This is achieved by performing a SOAP call to Service XYZ.
        * For performance reasons, results will be cached for 24 hours.
        * Blah, blah, blah.
        */
       public function findAllUsers() {
           // here be dragons
       }
   }
   

---

1. On a side note: If you need to document how your method does what it does, it's maybe too complex and should be broken down into smaller units.