PhpDoc用于接口和类实现接口 - 差异 [英] PhpDoc for interface and class implementing interface - difference

问题描述

问题很简单 - 我应该如何区分phpdoc的接口和类实现接口？应该/他们可以是相同的或者也许接口文档应该尽可能一般，类实现这个接口更具体？

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?

我包括一个方法phpDoc从我的真正的代码：

I include one method phpDoc from my real code:

我的介面：

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

文档应该是什么样子的？更实用的接口和更具体的类实现这个接口？

Is that the way documentation should look like? More general for interface and more specific for class implementing this interface?

推荐答案

直接回答你的直接问题是是。接口上更一般的描述是好的，你应该只在类描述中增加这个信息。我会选择不是重复类方法上的标签，因为这样做，您防止您的界面的信息被看到...你实际上覆盖它。我意识到这里的工作问题是，不是所有的IDE自动完成和信息弹出窗口正确地正确处理这种继承分析（或在所有）。

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).

作为一个长期phpDocumentor和IDE用户，我的最佳做法是实际上仅记录界面。当涉及到实现接口的类的docblock时，我将包括的唯一信息是@internal标签来编写开发人员特定的信息，不应该出现在接口API文档。我希望我的IDE知道类的实现方法应该从其接口的docblock中拉它的文档。

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.

{@inheritdoc}在野外使用是不一致的打算完成，我认为在phpDocumentor 1.x处理标签的bug随着时间的推移，人们尝试不同的方式使用它，然后导致IDEs也对它不同。因此，它不再是我使用的一种做法。

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.

这篇关于PhpDoc用于接口和类实现接口 - 差异的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！