PHP プロジェクトでは、メイン アプリケーションにフロント コントローラー ロジックが使用されている場合でも、多くのスタンドアロン スクリプトや ajax スニペットなどが存在する可能性があります。
スクリプトの最初のコメント ブロックで、スクリプトが受け入れる/要求する GET および/または POST パラメーターと、それらがどのタイプであるかを定義する標準化された方法 (PHPDoc またはその他) はありますか?
私は通常@param、ファイルが関数であるかのように s を追加@returnし、スクリプトの動作と戻り値の説明を追加するだけで自分自身を助けますが、私が知らないより専門的な方法があるかもしれません。
phpDocumentor は、ファイルレベルのdocblockの@paramおよび@returnタグを好まない...
Mr-skの回答に従って、それらをドキュメント化する別のファイルを選択した場合、@linkを使用してそこを指すことができますが、ファイルのドキュメントページにすぐには表示されません...ただ情報を見るためにクリックする必要があるハイパーリンク。そのファイルの内容のいずれかをスクリプト ファイルのドキュメント ページに表示したい場合は、インラインの{@example}タグを使用して、またはその中の特定の行だけを指すことができます。例: {@example /path/ to/file 3 5}を使用して、3 行目から 5 行目のみを表示します。
このシナリオでは、ファイルレベルの docblock の長い説明で物事を説明することを選択するでしょう。実際には、phpDocumentor がコード要素として認識する場所にパラメーターをタグ付けする直接的な方法はないからです。説明で使用したパラメーターのいずれかが、実際にコード内の別の場所に由来する文書化されたコード要素である場合、インラインの{@link}タグを使用してそのコード要素を指します。
たとえば、別のコード ファイルで定義されたいくつかの定数があり、それらの要素の独自のドキュメントが、その別のファイルが解析されるときに生成されるとします。スクリプトのみのファイル (あなたのものなど) のファイルレベルの docblock に書いた私の長い説明が、これらの定数をパラメーターとして説明している場合、私の文は次のようになります。
If $POST['foo'] is set, its value should always be either {@link BAR_CONST} or {@link BAZ_CONST}.
参考文献:
ペッカ、
APIとのやり取りを文書化するためにWADLを使用することを検討します。あなたの質問に直接答えているわけではありません。これは、ソース コード ドキュメント、その XML から生成されておらず、個別に維持されているためです。
それはこれに直接答えます：
スクリプトが受け入れる/要求するGETおよび/またはPOSTパラメータと、それらのタイプ
URI パラメーター、受け入れられたコンテンツ タイプ、エラー コード/応答/ペイロードと共に、サンプル ペイロードをドキュメントに配置できます。これは非常に価値があり、WADL を使用すると、誰かが API に対してクライアントをコーディングできます。
詳細情報: http://research.sun.com/techrep/2006/abstract-153.html および: http://en.wikipedia.org/wiki/Web_Application_Description_Language
使用する@usesか、@see
現在使用して@usesいるのは、読みやすく、意味があるためです
参照: https://phpdoc.org/docs/latest/references/phpdoc/tags/uses.html