Stack Overflow is a community of 4.7 million programmers, just like you, helping each other.

Join them; it only takes a minute:

Sign up
Join the Stack Overflow community to:
  1. Ask programming questions
  2. Answer and help your peers
  3. Get recognized for your expertise

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?

share|improve this question
    
I think you shouldn't copy all phpDoc from interface to implementation class. Only tags which differ from their counterparts in interface. For the rest you can leave link by @see tag – hindmost Jul 30 '14 at 12:00
up vote 3 down vote accepted

The direct answer to your direct question is "yes". The more general descriptions on the interface are good, and you should only augment that info in the class descriptions. I would choose to not duplicate the tags on the class methods, because by doing so, you prevent your interface's information from being seen... you're effectively overriding it. I realize the working problem here is that not all IDE autocompletions and info popups correctly handle such inheritance analysis correctly (or at all).

As a longtime phpDocumentor and IDE user, my best practice is to actually only document the interface. When it comes to docblocks for the classes that implement the interface, the only info I'd include there is the @internal tag to write developer-specific info that should not appear on the interface API docs. I expect my IDE to know that the class's implementing method should pull its docs from the interface's docblock.

Usage of {@inheritdoc} in the wild is inconsistent on what it really intends to accomplish, and I think bugs in phpDocumentor 1.x's handling of that tag over time caused people to try different ways of using it, which then resulted in IDEs also treating it differently. As a result, it's no longer a practice I use at all.

share|improve this answer
    
Thank you for your answer. But what to do in case if some parameters have more functionality? For example in interface I include only information about objectId: Name of object to store in cache in in class I added more info that if it start with : ... Other class implementing interface may not have such feature and do it in different why (for example remove everything that is not a letter not digit). Should I in that case omit in class the first part Name of object. because it was already mentioned in interface? – Marcin Nabiałek Jul 30 '14 at 18:55
    
For the use case you describe, your only option is to override the interface's docs by including the class method docblocks. However, I'd argue that if your implementation here requires such extra info for the API user to be aware of, but other implementations of the same interface do not adhere to that same behavior, the class is not truly abiding by the interface's contract, and trouble may occur if the API user changes from using this class to another class. This kind of difficulty in writing the docs is a "code smell" to me that makes me revisit my design :-) – ashnazg Jul 31 '14 at 21:02

A part of the answer is here.

/**
 * @implements CacheInterface
 */
class Cache implements CacheInterface
share|improve this answer
    
I saw this question before asking but it doesn't clarify how create documentation for me – Marcin Nabiałek Jul 30 '14 at 12:25

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.