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，也不是IDE中的代码辅助，则标记的顺序不会影响/ rendered输出/。

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

我一直在使用php docblock大约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阶段...）可以稍后进行。

我会用空格将类似的东西分开。

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