PhpDoc用于接口和实现接口的类-差异

问题很简单-对于接口和类实现接口，我应该如何区别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
    }
}

我的类实现接口：

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

文档应该是这样的吗？对于接口更一般，对于实现此接口的类更具体？

答案的一部分是

---

对你的直接问题的直接回答是“是”。接口上更一般的描述是好的，您应该只在类描述中增加这些信息。我会选择不复制类方法上的标记，因为这样做可以防止看到接口的信息。。。你实际上是在超越它。我意识到这里的工作问题是不是所有的IDE自动完成和信息弹出都能正确地处理这种继承分析（或者根本不能）

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

---

{@InheritationDoc}在野外的使用与它真正想要实现的目标不一致，我认为phpDocumentor 1.x中随着时间的推移处理该标记的错误导致人们尝试不同的使用方法，这导致IDE也对其进行了不同的处理。因此，我不再使用它。

我认为不应该将所有phpDoc从接口复制到实现类。仅限与接口中的对应项不同的标记。剩下的你可以留下linkby tagI在提问之前看到了这个问题，但它并没有说明当你需要添加界面到traits时，为meits创建文档是如何有用的谢谢你的回答。但如果某些参数具有更多功能，该怎么办？例如，在接口中，我只包含有关objectId的信息：

要存储在缓存中的对象的名称

，在类中，我添加了更多信息，如果它以

开头：

。。。其他实现接口的类可能并没有这样的特性，并以不同的方式执行（例如，删除所有不是字母而不是数字的内容）。在这种情况下，我是否应该在类中省略对象名称的第一部分。，因为它已经在接口中提到了？对于您描述的用例，您唯一的选择是通过包含类方法docblocks来覆盖接口的文档。但是，我认为，如果您的实现需要API用户知道这些额外的信息，但同一接口的其他实现不遵循相同的行为，那么该类就没有真正遵守接口的约定，如果API用户从使用该类更改为使用另一个类，则可能会出现问题。编写文档的这种困难对我来说是一种“代码味道”，让我重新审视我的设计：-）