PHP文檔中標籤的順序

什麼是PHP文檔中標籤的確切順序？是否有一些會議要遵循？或者它是「隨機的」？例如：PHP文檔中標籤的順序

 * 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

是迄今爲止「等效」？

來源

2015-05-14 mboullouz

該命令是無關的，我不知道任何約定。不過，我會建議始終使用相同的順序，因爲它提高了可讀性。

來源

2015-05-14 10:50:48 van

如果您通過phpdocumentor構建html/chm，或者IDE中的代碼輔助，則標記的順序不會影響/呈現的輸出。

但是，docblock需要在原地可讀，正如@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，它有一個滿意的要求，一個句號。在索引頁面和導航上，您只能看到這些。所以我仍然這樣做。

我傾向於按照您想閱讀的順序排列內容 - 很簡單。優先考慮show-stoppers（如棄用） - 不要浪費人們閱讀死亡函數的時間。如果有一個關鍵的TODO（即班級/方法沒有完成），我會把它放在最上面，可選的待辦事項（很好，第2階段...）可以晚點。

而我會用空格分隔類似東西的塊。

這對我來說很有意義，但它部分是一種風格/熟悉的東西。

來源

2015-05-14 11:41:37 scipilot

PHP文檔中標籤的順序

回答

相關問題