用于接口和实现接口的类的 PhpDoc - 区别 [关闭]

Question

这个问题很简单——我应该如何区分接口和类实现接口的 phpdoc？它们应该/可以相同，或者接口文档应该尽可能通用，并且实现此接口的类更具体？

我从我的真实代码中包含了一种方法 phpDoc：

我的界面：

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

文档应该是这样的吗？接口更通用，实现该接口的类更具体？

Answer 1

部分答案是here。

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

Answer 2

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

作为一个长期使用 phpDocumentor 和 IDE 的用户，我的最佳实践是实际上只记录界面。当涉及实现接口的类的文档块时，我要包含的唯一信息是 @internal 标记，用于编写不应出现在接口 API 文档中的开发人员特定信息。我希望我的 IDE 知道该类的实现方法应该从接口的文档块中提取其文档。

在野外使用 {@inheritdoc} 与其真正想要实现的目标不一致，我认为随着时间的推移 phpDocumentor 1.x 处理该标签的错误导致人们尝试不同的使用方式，然后导致在 IDE 中也有不同的处理方式。因此，我根本不再使用它。