自動ドキュメントツール

Rubyで言えばrDocに代表されるツールがあるが、最近仕事のプロジェクトで取り入れ始めたので公開してみる。

経緯として、会社のドキュメントはほとんどなく、開発に必要な仕様書も仕様書とはいえないレベルでお世辞にも良いとはいえない状態。
最近のプロジェクトでは1からドキュメントもきちんと作りましょうと自分がうるさく言っているのですが、時間もなく難しい状態。
エンジニア側はせめてとのことで始めたのがrDoc系の自動ドキュメント作成ツール(正式にはなんという用語なのでしょうね)。

Ruby

YARD

rDocがあるが、どうも最近のは昔とはテンプレートが変わっているようだ。
で、どうもイマイチなので次世代rDocと言われているYARDを試してみると結構良い感じ。
書き方も一貫性があったり、@hogeでパラメータを書けたり、書く側としても問題ない状態。
Markdownで出力する方法が良く分かっていないのが問題。HTMLだとgithub上でドキュメントが見づらい。

autodoc

APIのドキュメントはこれ。
rspecからレスポンスのドキュメントが作成されるので嬉しい。
出力がMarkdownなのも嬉しい。githubで見やすいよね。
あと、rspecの強制にもなるしね。

Javascript

YUIDoc

幾つか試しましたが、結局これが一番まともっぽい。
ただ、クラスが必要なのがちょっと。JSってクラスなくても作れるので、クラス用コメントをファイル名代わりに書いて逃げています。
出力はHTMLなので、Markdownへの方法が知りたいです。
Rubyに比べるとJSのこのあたりって全般的にイマイチなイメージです。

その他

ツールとはちょっと違うけど、ドキュメントについてメモ

仕様書

みんな嫌がる仕様書だけど、無いと話にならない。言った言わないの下らん争い、引き継ぎ、新人がプロジェクトを理解する方法、色々な場面で必要なのですが作られない場合が多い。
今回はMarkdownで書いてgithub上で管理しています。

doxygen

Cとかではこれをよく使っていました。いまでもCのプロジェクトを作るのであればこれを使うと思います。

graphviz

単体でも使えるツールですが、doxygenと合わせてよく使います。
C++だとクラス図を書いたりとか色々便利。