是否有用於記錄GET/POST參數的標準？

Question

在一個PHP項目中，即使前端控制器邏輯用於主應用程序，也可能有許多獨立腳本，ajax片段等等。

是否有一個標準化的方式 - 無論是PHPDoc或其他 - 在腳本的第一個註釋塊中定義腳本將接受/要求的GET和/或POST參數以及它們是哪種類型？

我通常只需增加@param就好像該文件是一個函數，並提供了一個@return解釋腳本執行和返回的內容，但也許有一種我不知道的更專門的方法。

Answer 1

的phpDocumentor不會喜歡在文件級的docblock @param和@return標籤...

如果選擇根據Mr-sk的回答，您可以使用@link指向那裏，但它不會立即顯示在其中你的文件的文檔頁面...它只是一個超鏈接，你必須點擊才能看到信息。如果您希望在腳本文件的文檔頁面上顯示該文件的任何內容，則可以使用內聯{@ example 012d標記指向該文件，或者甚至只是其中的某些行，例如， {@example/path/to/file 3 5}只顯示第三行到第五行。

在這種情況下，我可能會選擇在文檔級docblock的長描述中解釋一些事情，因爲實際上沒有直接標記參數的方法，無論如何phpDocumentor會將它們識別爲代碼元素。如果我在描述中使用的任何參數確實是源自代碼中其他位置的代碼元素，我會使用內聯標記指向該代碼元素。

例如，假設在另一個代碼文件中定義了一些常量，並且在解析其他文件時生成了這些元素自己的文檔。如果我說我在一個只有腳本文件（像你這樣）的文件級的docblock寫長篇描述那些常量作爲參數說話，然後我的一句話可能是：

If $POST['foo'] is set, its value should always be either {@link BAR_CONST} or {@link BAZ_CONST}.

參考文獻：

• 直列{} @example - http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.inlineexample.pkg.html
• 直列@的{link} - http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.inlinelink.pkg.html

Answer 2

Pekka，

我會研究使用WADL來與您的API進行文檔交互。它不直接回答你的問題 - 因爲這不是從源代碼文檔，XML生成的，而是單獨維護的。

它不直接回答這個問題：

什麼GET和/或POST參數 腳本將接受/要求和 他們是哪種類型的

您可以將樣品有效載荷在文檔，以及URI參數，接受的內容類型，錯誤代碼/響應/有效載荷。我覺得它非常有價值，並且使用WADL，有人可以針對您的API對客戶端進行編碼。

欲瞭解更多信息：http://research.sun.com/techrep/2006/abstract-153.html 和：http://en.wikipedia.org/wiki/Web_Application_Description_Language

Answer 3

我會用@uses或@see 目前我使用@uses因爲它讀取更好，是有道理的

參考：https://phpdoc.org/docs/latest/references/phpdoc/tags/uses.html