PhpDoc for interface and class implementation interface - difference

Question

The question is quite simple - how do I distinguish phpdoc for the interface and the class implementation interface? Should they be the same or maybe the front-end documentation should be as general as possible, and the class implementing this interface more specific?

I include one phpDoc method from my real code:

My interface:

interface CacheInterface { /** * Adds data to cache * * @param string $objectId Name of object to store in cache * @param mixed $objectValue Data to store in cache * @param mixed $lifetime Lifetime of cache file * @param string $group Name of cache group. * @param array $params Parameters that distinct cache files. * @param array $files Name of files that are checked if cache is valid. * @return bool True if cache was created, false if cache was not created */ public function put( $objectId, $objectValue, $lifetime = null, $group = null, $params = array(), $files = array() ); } 

Class implementation interface:

 class Cache implements CacheInterface { /** * Adds data to cache * * @param string $objectId Name of object. If it begins with : cache filename will be created using hash * function. If name doesn't begin with : it should use ASCII characters to avoid * problems with filenames * @param mixed $objectValue Data to store in cache * @param mixed $lifetime Lifetime of cache file. If none provided it will use the one set in contructor. * Possible lifetime values: time in seconds (3600 means that cache is valid * for 1 hour = 3600 seconds) or one of TIME_ constants @see CacheInterface * @param string $group Name of cache group. If none/null provided it will use the one set in constructor. * Sub-groups should be created using | for example group|subgroup|subgroup2 * @param array $params Parameters that distinct cache files. You can for example pass here array('id' => 1) * to set cache for user id. If $params is not empty, they are also used to generate * file name. That way they should rather include simple ASCII values * @param array $files Name of files that are checked if cache is valid. It should be numerical array * (not assosiative). If files are not empty when getting data from cache it checked * wheteher those files exists and are created earlier than cache was created. * If any of those conditions is not met cache file is treated as invalid * @return bool True if cache was created, false if cache was not created */ public function put( $objectId, $objectValue, $lifetime = null, $group = null, $params = array(), $files = array() ) { // implementation here } } 

What does the documentation look like? More general to the interface and more specific to the class implementing this interface?

Answer 1

The direct answer to your direct question is yes. More general interface descriptions are good, and you should only increase this information in class descriptions. I would prefer not to duplicate tags in class methods, because by doing this you do not see information about your interface ... you effectively overlap it. I understand that the working problem is that not all IDE autocomplete and information pop-ups correctly handle this inheritance analysis correctly (or in general).

As a longtime user of phpDocumentor and IDE, my best practice is to actually document the interface. When it comes to docblocks for classes that implement the interface, the only information I would include is the @internal tag to write information about a particular developer, which should not appear in interface API documents. I expect my IDE to find out that the class implementation method should pull its documents from the docblock interface.

Using {@inheritdoc} in the wild is incompatible with what it really intends to execute, and I think that errors in processing phpDocumentor 1.x of this tag over time forced people to try different ways to use them, the IDE also considers it in different ways. As a result, I no longer use this practice.

Answer 2

Part of the answer is here .

 /** * @implements CacheInterface */ class Cache implements CacheInterface