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

直接回答你的直接问题是"是".界面上更一般的描述是好的,你应该只在类描述中增加那些信息.我会选择不复制类方法上的标记,因为这样做会阻止您的界面信息被发现......您实际上是在覆盖它.我意识到这里的工作问题是并非所有IDE自动完成和信息弹出窗口都能正确处理这种继承分析(或根本没有).

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

在野外使用{@inheritdoc}与它真正打算完成的事情是不一致的,我认为phpDocumentor 1.x随着时间的推移处理该标记的错误导致人们尝试不同的使用方式,这导致IDE也对待它的方式不同 结果,它不再是我使用的练习.