php - php 文档中的标签顺序

Question

php doc中标签的确切顺序是什么？是否有一些约定要遵循？还是“随机”？
例如:

     * Some instructions 
     * @example $entity->id; $entity->content ...
     * @throws MyException
     * @return mixed
     * @see ThisClass

     * Some instructions 
     * @throws MyException
     * @example $entity->id; $entity->content ...
     * @see ThisClass
     * @return mixed

到目前为止是“等效的”吗？

Answer 1

如果您通过 phpdocumentor 构建 html/chm，则标记的顺序不会影响/rendered 输出，也不会影响 IDE 中的代码辅助。

然而，文档块需要就地可读，正如@van 所建议的那样，一致性将帮助您和其他开发人员快速找到信息。我认为它就像一个 .md 文件，它应该是可读的渲染或原始的。

我已经使用 php docblocks 大约 10 年了，并且倾向于使用以下格式。

/**
* One-line introduction followed by a full stop (for the title in some templates).
*
* @deprecated this should be prominent so I often put it at the top!
* @todo Critical TODO ... this function doesn't work yet!
* 
* A fuller paragraph detailing stuff.
* A fuller paragraph detailing stuff.
* A fuller paragraph detailing stuff.
* @see is part of the detail
* @example is part of the detail
*
* @todo following on from the detail - what's not been done.
* @todo polishing not done, N2H's.
* 
* @throws and other technical aspecs I'd put here - if any.
* 
* @param Then params in a block - in the ACTUAL order of the params
* @param phpstorm always separates the last param from return
* @param with blank line so i've started going with that!
* 
* @return is always the last tag - makes sense.
*/ 

一行介绍是 PHPDocumentor 1 的后遗症，它有一个句号作为要求。在索引页面和导航上，您只看到这些。所以我还是这样做了。

我倾向于按照你想要阅读的顺序来排序——非常简单。优先考虑诸如弃用之类的表演障碍 - 不要浪费人们的时间阅读死函数。如果有一个关键的待办事项(即类/方法未完成)，我会将其放在顶部，可选的待办事项(很好，第 2 阶段......)可以稍后进行。

我会用空格分隔相似的东西块。

这对我来说很有意义，但这在一定程度上是一种风格/熟悉程度。