二年前に autodoc を導入したが、現在はもはや誰も見てないし使ってないね、という話を社内でしたら、「使い始めた話だけじゃなくて、やめちゃった話もブログに書くべき」と指摘され、確かに誠実な姿勢とはいえないなと反省したのでこの記事を書いています。
恥を忍んで現状を明かすと、 master ブランチに push されたタイミングで実行される Jenkins のジョブが半年ずっと fail していた、ということに昨日気づいた体たらく。そもそも生成された markdown ドキュメントを push していたリポジトリがとっくの昔に削除されていたと思っていた。
うまくいかなかった原因の分析:
Quipper の Internal API は非常に込み入ったデータ構造を返すものがほとんどで、お世辞にも「きれいな RESTful API」とは言えない。なので request spec を書く際に、完璧なテストデータを用意しきれておらず、アサーションもちょっと粗い（JSON が所定のフィールドを持っているか、フィールドの値の型は何か、という詳細なレベルのテストはモデル層のユニットテストとして書いているので request spec で重複するテストを網羅的に書かない）なので、 autodoc が生成するドキュメントに記載されるレスポンスデータは、「あるべきデータ構造・データ型」でもなければ「本番環境の API が実際に返しうるデータ構造・データ型」でもない、ということがありえる。つまり、ドキュメントの信頼性が低い。
autodoc で生成されるドキュメントの精度を上げるために request spec で込み入ったデータ構造を再現したテストを書く、というのは労力に見合わない。大量のテストデータを生成しなければいけないのでテストコードは太り、テスト時間は長くなる。しかもあくまでテストデータにすぎないので、実際にありえるパターンすべてを網羅するのが難しい。ツールを活かすために別の負担が増すくらいならふつうにドキュメントを書いたほうがよい。がそんな余裕はなく、またぶっちゃけそこまで API ドキュメントが必要とされてもこなかった（ほぼ全員 Ruby と Rails の読み書きができるので実装を読んだほうがはやいし確実）
ということで、銀の弾丸はなかったという話でした。
