最近、業務内でマークアップだけでなく、JavaScriptやPHPを書くことも増えてきました。

再利用とか拡張性とかを考えながらClassを書くことも増えてきたのですが、ガリガリ書いていく上で、やっぱり未来の自分のことを考えるとコメントを書いておいたほうがいいよなと思いコメントも書くようにしています。

何をしているメソッドなのか分かるといいよねと思って調べていると、PHPDocとかJSDocというものがありました。

この形式で書いておいたほうが、後々ドキュメントを生成できたり、何を入れたら動いて、何が返ってくるみたいな情報も分かるし良いんじゃないかなと思いそれっぽく書いています。

しかし、やり始めた当初、引数や返り値を一個一個拾って書いていくのは面倒くさいなと数分で投げかけていたのですが、良いパッケージがありました。今回紹介するdocblockrです。

ドキュメントを見るとまだまだ少ないですが、今使っている言語においては十分です。

よく使うのが、Class内のメソッドに対してのコメントなのですが、先にメソッドを書いておいてコメントを書くために /** まで書き改行すると、メソッド自体の説明と、メソッドで使っている引数や返り値なんかを必要に応じて抽出し、型や説明を書くための雛形を生成してくれます。

メソッドだけでなく、変数なんかにも使えるようで結構使えるパッケージかなと思います。

Docを書くなら入れておいて損は無いパッケージだと思うのでぜひ一度入れて触ってみてください。

docblockr