PhpDoc для интерфейса и интерфейса реализации класса – разница

Вопрос довольно прост – как мне отличать phpdoc для интерфейса и интерфейса реализации класса? Должны ли они быть одинаковыми или, может быть, интерфейсная документация должна быть как можно более общей, а класс, реализующий этот интерфейс более конкретным?

Я включаю один метод phpDoc из моего реального кода:

• phpdoc: Каков правильный способ документирования константы
• Каков правильный способ написания PHPDocs для констант?
• Каков правильный способ документировать PHP-константы (определить) с помощью phpDocumentor
• PHPDocumentor 2 и PHP 7 с проблемами opcache в Doctrine
• Тип PHPStorm, указывающий подклассы базового слоя

Мой интерфейс:

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 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's 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's 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 } } 

Так должно выглядеть документация? Более общий для интерфейса и более конкретный для класса, реализующего этот интерфейс?

• Анализ комментариев PHP Doc в структуру данных
• Eclipse PDT и пользовательские аннотации PHPDoc
• PHPDoc: документирование функции с переменным числом аргументов
• Как я могу указать массив объектов в PhpDoc
• Как использовать PHPdoc в Eclipse

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