Rails環境でのドキュメントの自動化
仕事しているとドキュメント大事ですよね。
いつ人の移動があるか分からないし、新しく追加されても忙しいと説明する時間もなかったり。
そういう管理しているのが問題なのですがそれはそれとして、やぱっぱりドキュメントはあるに越したことはないです。
ということで、仕様書とかは別にしても現状の成果物に対してのドキュメントの自動化を行っています。
ドキュメントを作りたいけど忙しい方たちはこれを行うだけでも大分楽になるかと。
YARD/RDoc
昔からよくあるソースコードから作るドキュメント。
DoxygenやJavaDocなどのRubyバージョンですね。
適切なコメントを書くと、クラスとそのメソッドのドキュメントを作成してくれます。
Rdocは便利なのですが、YARDの方が一貫性があるなどより良い感じですので、こちらを採用しています。
最悪コメントを書かなくてもとりあえずのドキュメント化はしてくるようですし、
rails-erd
voormedia/rails-erd · GitHub
DataBaseからER図を自動生成してくれます。
これがあると無いとでは大違いですね。
schemadoc
rubylibs/schemadoc · GitHub
こちらはDatabaseからテーブルとカラムの一覧をjsonで出力してくれます。
Railsのダメなところはtable宣言を見たい場合は、Databaseを直接見るぐらいしか方法がないことです。
migrationは運営していくにつれて増加しますしカラムの変更を行うと複数のmigrationファイルが増えていって理解不可能、modelを見てもテーブルの状態は書いていないです。
gemでmodelに出してくれるものもあるようですが、マネージャー等からするとドキュメントはやっぱり別途必要。
ということで、schemadocだと自動生成してくれるのでおすすめです。
