Divisionの金城(@o0h_)と申します。10月にBASEに入社しまして、ブログ投稿は本稿が初となります。掲題の件に入らせていただきます。Tagsについての決め事」です。1PHP-FIGは、元々はオートローディング活用のための取り組み2を契機として作られた団体です3。「PHPの書き方」に強い関心を持っていたとも言えます。Guide」であることからも「初期にフォーカスしていた領域がどこであるか?」というのを伺い知れるのではないでしょうか。言い加えると、PSR-0,2のみが現状でDeprecatedステータスに配置されています4。Styleに関する話題であるという事です。ある意味で「実装のし易さ」と同じくらいに「コードを読みやすく・違和感なく」運用していく事に重きを置いていた団体が、「doccomment/tagの書き方について未だに標準化できていない」・・というのは、ちょっと面白いと思いませんか?一体どんな経緯があったのでしょうね。そんな訳で、本稿では「PSR-19なんなのよ」という事について見ていきたいと思います。commentというと「いろんな方言がある」という印象を抱いた方も多いと思います。commentについて「PHPDoc」6と表記することとします。)「phpDocumentorのそれに従おう」「いやPhpStormに合わせりゃよくない?」「Phanが」「PHPStanが」といったソレです。それぞれ目的が違うものであり、自分達の目的を果たすために独自の拡張的な記法なども導入していく事には必然性があります。完全に統一され得るものではないでしょう。・・とはいえ、いち利用者的な観点からすると「似たような事は同じ書き方で出来ればいいのにな」と思う訳です。「相互運用性のための決まり事」があると良かろうなぁという場面で、PSRに目が向きます。それがPSR-5です。このPSR-5、提案自体は数年前になされたものの、「広範に支持されるような勧告」といった地位にまでは至りませんでした。結局は「色々な書き方がある内のいち方言」のような雰囲気のままです。して遂には議論が停止、草案は「STATUS:ABANDONED」7に・・・・なったのですが、これが再提案されて「DRAFT」化8、今に至ります。いった訳で「5番」などという非常に若い番号が未だに議論されている訳ですね。membersとして「phpDocumentetor」「PhpStorm」「Psalm」「PHPStan」の関係者をそれぞれ迎えています。これは現実的な落とし所を見つけつつ、各ツールのサポートの観点からも実用性を伴う状況が実現できるのではないでしょうか。期待ですね!昨年時点でのPSR-5の状況については、こちらの記事に大変よくまとまっておりました。qiita.comPSR-19PSR-5の「復活」にあたって、一緒に提出されているのがPSR-19です。これは、PSR-5にまとまっていた内容を2つに分けようという提案9に基づくものになります。PSR-5についてはPHPDocのフォーマットを、PSR-19についてはタグの種類を決める内容になります。二者が分割された動機については「PHPdocのフォーマット(PSR-5)を一般的な内容にしつつ、タグの内容(PSR-19)は拡充しやすくする。将来的にはPHPDoc外でも利用可能になることを見越して」と説明されています。$bar;のようなものでしょうか。いうことで、本稿は(既にその内容には見慣れているであろうPSR-5よりも)PSR-19の中身はどうなっているのかな?と興味を持って調べてみるものです。中身を見てみる現時点でのPSR-19のproposalはこちらから確認できます。GitHubまた、GitHub上での議論(PR)についてはラベルで辿ってみるのが良いでしょう。GitHub中身を見てみると、5つのセクションに分かれています。{@inheritDoc}を用いることなどそして第5セクションが「タグ」の定義です。お馴染みなのではないでしょうか。クラスやメソッドの機能に関連するもので、PhpStormなどのIDEやPHPStan・Phanといった静的解析を利用している場合には欠かせません。残る内容について、その書式や意味を掻い摘んで見ていきましょう。独断にて、関連するタグごとに以下の4つの群にまとめながら取り上げていきます。「論理上の区分」を示すために用いるものと説明されています。区切って記述する」と規定していたり、「Namespaceと完全に一致する場合に@packageタグを利用することは推奨しない」と言及されています。Namespaceで表現される「機能的な区分」とは別に、論理上の区分を明らかにしておきたいという場合に利用されるものになります。package」に付与されるものと説明されています。ようなものを区別するためのものです。belongs.」と説明されています。package」に付与されるものと説明されています。このタグが規定されている動機についても説明していて、1つには「ライブラリの作者が、ユーザーに対して"破壊的な変更を含む可能性がある"ということを示すため」2つには「静的解析時に、パッケージ外からの利用を警告できるようにするため」というポイントを取り上げています。実際に、PhpStormでは違反的な利用に対して警告を出すようになっています。@copyright@authorは、その作者や重大な改修を行った人を示すものと説明されています。@copyrightはそのコードに対する著作権と説明されています。関連する情報を示すものと説明されています。書かれていますが、ここは「Webサイト」というより「情報の掲載されているWebサイト」といったニュアンスで解釈するほうが意味する所に近いのかな?と思います)@linkタグを利用する場合には、絶対URIで示すように指示されています。インラインでの利用も想定されています。関連するリソースを示すものと説明されています。@linkはURIだったのに対し、こちらはURI以外のリソースを利用することも可能です。他のクラスやメソッドがあり、そのような要素を指す場合には「FQSEN」を利用するようにと規定されています10。?)という説明を載せるべきだとされています(SHOULD)。description)、こちらが「べき」なのは、「ドキュメント」以外のリソースも扱えるからでしょうか。利用される要素やファイル名を示すものと説明されています。記述できるのは同じプロジェクト内のリソースに限るとされています。そのために、URI等の利用は禁止です。利用することが出来ます)例として、「コントローラーのメソッドに対して、描画されるView/templateファイル名を示す」といった内容が挙げられています。これは、どういった場合に嬉しいのでしょうか?例えば動的な関数の呼び出しを行っている場合やマジックメソッド経由で利用しているメソッドについて、@usesを用いてエディタや静的解析ツールに「実際に使っているよ!」ということを知らせることが出来ます。ついては、現時点ではPSR上での規定はありませんでした。バージョン・更新に関わるもの現行の状態や更新履歴といった情報です@version@versionは、現在のバージョン情報とそのバージョンで提供された内容を示すものと説明されています。セマンティックバージョンを利用して言及すること、説明文を加えることを推奨されています(RECOMMENDED)。@since@sinceは提供が開始された(もしくは内容が現行の状態に変更された)バージョンを示すものと説明されています。(@versionと同様に)セマンティックバージョンを利用して言及すること、説明文を加えることを推奨されています(RECOMMENDED)。「2.0.4から、第3引数が追加された」といった内容などは@sinceで示すのが良さそうです。@deprecated@deprecatedは廃止予定・将来のバージョンにて削除されるものを示すものと説明されています。廃止予定とされた理由について、説明文を加えることも可能とされています(MAY)。実施される(開発・改修される)べきことを示すものと説明されています。このタグには必ず説明を入れなければならない(MUST)とのことです。(todoが「バージョンに関するもの」か?というと、「将来的な変更に関するもの」という意味では、この群に属するのではないでしょうか)その他の提案内容についてここに列挙したタグは既にproposalにコミットされているもので、ある程度の同意を得たものという扱いになります。「今はリストに含まれている」というだけであり、最終的には削除されるかもしれないし他のタグが追加される可能性もあります。type」についての提案がなされています。github.comこれは、TypeScriptでいうneverに相当するもので、exit()やtrigger_error()の発火により「呼び出し元に処理を戻さない」性質を説明するものです。no-returnという表記によって扱われています。PSR-19についても、いくつかのタグの追加に関するPRが作成されている状況です。まとめざっくりと、現時点でPSR-19として規定されているPHPDocのタグについて見ていきました。多くのタグは「定番化」しているもので、既存のコードに対して衝撃を与える事はないように思います。実際に、PSR自らがInterfaceの定義等において既に利用している状況が見受けられます。PSR自体は決して「PHPを書く際に従わなければならない」ものではなく、「フレームワークやツールを作る時に準拠しておくことで、何か良いことがあると良いよね」程度のものです。そのため、実質的なデファクトスタンダード(今だとphpDocumentorになるでしょうか)が存在すれば、大きく困ることもありません。実際に、過去に議論が停滞したのも「困らなかったから」という側面はあるでしょう。個人的には、先述の通り「PSR自体がPHPDocを利用している」こともあり、やはり明確な定義を持つべきなのではないかな?と考えています。繰り返しになりますが、PSR-5,PSR-19はその内容がまだ確定しておらず、現在進行系で議論がなされている状況にあります。ここにまとめた内容も採択時には変更されているかもしれません。それでも、その内容や議論に興味を持つことは、今っぽいPHPを考える上で多少なり意味のあることではないかと考えます。PSRはその性質的に「最大公約数」を示す力も持っていると捉えているからです。皆さんもぜひ、PSR-5/PSR-19の内容を眺めながら「ドキュメント性能の高いソースコード」について想いを馳せてみるのはいかがでしょうか!ここまで読んでいただきありがとうございました。Group」は「PHP本体への提案」を目指して結成されたグループです。「標準化」に際しては考慮すべき点が多く困難性があったため、「より柔軟な提案をするために、言語仕様そのものではなく、その上に乗るプラクティスとして規約を求めよう」と方向転換をして今のPHP-FIGが生まれました。そのため、「広い範囲を扱う」というのは、サジ加減はあれど、FIGにおける本質的な振る舞いだと私は解釈しています。Cache」や「PSR-7をコアとした一連のHTTP関連Interface(15,17,18)」もあるので、「特定の領域について深める・広める」という事自体は他にも積極的に行われています。)の開発チームによるブログです。Groupの大木です。Developerをしている東口です。Groupのマネージャーをしている山田です。12/1から始まっ...Archiveスターをつけました引用をストックしましたストック一覧を見る閉じる引用するにはまずログインしてくださいログイン閉じる引用をストックできませんでした。再度お試しください閉じる限定公開記事のため引用できません。