The question is quite simple - how should I differ phpdoc for interface and for class implementing interface? Should/Can they be the same or maybe interface documentation should be as general as possible and class implementing this interface more specific?
I include one method phpDoc 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()
);
}
My class implementing 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'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
}
}
Is that the way documentation should look like? More general for interface and more specific for class implementing this interface?
@see
tag – hindmost Jul 30 '14 at 12:00