問題タブ [docblocks]

崇高なテキスト用のプラグインDocBlockrが好きですが、コメントは少し違うものにしたいと思います。

通常の外観:

そして、それらをどのように表示したいか：

それで、type角括弧descriptionなしで、とにかくこれを行うことはありますか? []私はググってドキュメントを調べましたが、見つかりませんでした。下の画像は、ドキュメント ページから直接取得したものです。

コメントをするのがずっと簡単になるので、誰かがこれを手伝ってくれることを願っています.

エラーを処理するためのクラスがあり、try-throw-catchメカニズムを使用していません。

そのクラスを使用するコードにコメントする場合、@throws実際には何もスローしていなくても、タグを使用する必要がありますか?

編集（私の質問をより明確にするようにしてください）：

私の質問は、@throwsタグがコードの使用時にエラーが発生する可能性があることを意味し、何らかの方法でそれを処理していることを意味するのか、それともエラーが発生する可能性があり、throw具体的にキーワードを使用して処理していることを意味するのか?

の 1 行があるとしましょう。次のsummaryように修正する必要があります。

または、次のように書くこともできます:

私は 2 番目のオプションを好みますが、最初のオプションを使用するにはそれが必要ですか?

私はこの機能を持っています:

それを説明する DocBlock を作成したいと思います。この関数は、必要なコントローラーが有効な場合にのみコントローラー オブジェクトを返します。そうでない場合は、ErrorControllerクラスのインスタンスを作成しますが、値は返しません。この関数に適切な@returnタグを付けるにはどうすればよいですか?

私は、この非コード コード (ファイルの残りの部分の言語ではない、非コード) の現在の使用法と、そのような非コード コードの歴史に特に魅了されています。

場合によっては、これはメタプログラミングと呼ばれることもありますが、それがすべての場合をカバーしているとは思いません。

私はそれが多くのことに使用されているのを見てきました.(私の経験では)Cコメントの「Autodocs」で80年代までさかのぼり、ドキュメントを生成するために使用され、PHPのようなインタープリター言語での非常に複雑な現代の化身までずっとコメント ブロックにアノテーションがあり、それらはドキュメントに使用され、PHP 構文が不十分な場合に追加の意味を追加したり、その他の種類の「メタ」データを追加したりします。

その大きな寄せ集めのようです。そして、それについてどのように感じているかはまだわかりません。なんとなく間違っているようです。しかし、それでも私はそれに大きな有用性を見出しています。

私たちのコードのほぼすべてに含まれる非コード コードのこれらすべてのケースをカバーするためにどのような一般的な用語を使用するのか、また、この件名とその歴史、ベスト プラクティスなどに関する何らかの決定的な文書があるかどうか疑問に思っています。ありませんが、自分で調べて書きたいものとして興味があります。

たとえば、PHP の世界では、次のようなものがあります。

とにかく、私が見ているのは、この種のものを使用する非常に多くのツールですが、多くの重複と断片化があります. 少なくともPHPの世界では。そして、長年のプログラミングを振り返ってみると、この種のものは新しいものではないと思います.

この件について検索したかったのですが、探していたものを取得するのに適した検索用語がありませんでした。これは、そのような方法の起源、長年にわたってうまく機能したかどうか、ベストプラクティスなどに関する歴史的な文書でした.これはすべてメタプログラミングと見なされますか?

これらはどのような進化を遂げているのでしょうか。ある時点で言語の適切な部分になるのでしょうか、それとも新しい言語に組み込まれるのでしょうか?

この主題は一般的に私に興味を持っていたので、他の誰かがこの主題について決定的なテキストを書いたのではないかと思いました。

これらは実際にはドメイン固有言語の形式であると思います。ホスト言語は何かを表現することができないため、DSL を使用してコードに埋め込み (コメント内、またはホスト言語がサポートする機能 (注釈など) を使用) して、ホスト言語に関連付けたい他の情報を表現します。必ずしもコード フローに影響を与えることはありません。

私はちょうどこのような関数を書いた

しかし、docblock を作成するときに、それ@return \React\Promise\ExtendedPromiseInterfaceは非常に一般的であり、拒否または履行の場合に期待される返品をクライアントが理解するのに実際には役立たないことに気付きました。

この関数の結果として期待される値または例外を文書化するための確立された規則はありますか?これにより、クライアントはインターフェイスのみを見てこの関数をチェーンできますか?

phpUnit テスト docblock ではアノテーションを使用するのが通常である逆の規則が既にあり@coversます。

コードの一部を見ている場合、そのロジックを実行するテストを調べて、コードが何をすべきかを理解すると役立つことがよくあります。PHP では、関数を実行するために記述されたテストを見つける場所をコード内に文書化する規則はありますか? そうでない場合は、独自の規則を採用する予定であり、次のオプションのいずれかを検討しています。

• phpDocumentorアノテーションを使用する@internal
• のような完全にカスタムの注釈を使用します@spec
• docblock 内の単なるフリー コメントですが、すぐに認識できるパターンでスタイル設定されています
• 文書化しませんが、コードをコメントアウトしてテストされている場所を見つけ、テストスイートを実行して、どのテストが失敗するかを確認します。

これらの使用に対する警告はありますか?