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，那么标签的顺序不会影响/ render输出，也不会影响IDE中的代码辅助。

然而，docblock需要就地可读，正如@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的宿醉，它有一个完整的要求。在索引页面和导航上，这就是你所看到的。所以我仍然这样做。

我倾向于按照你想要的顺序订购东西 - 非常简单。优先考虑弃用等表演停止 - 不要浪费人们阅读死机功能的时间。如果有一个关键的TODO（即类/方法没有完成）我会把它放在顶部，可选的待办事项（很好，有阶段，第2阶段......）可以更晚。

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

这对我来说很有意义，但它部分是一种风格/熟悉的东西。

Answer 2

订单无关紧要，我不知道任何约定。但是我建议总是使用相同的顺序，因为它提高了可读性。

php doc中的标签顺序

2 个答案: