Docuss というものを書いた.Java のライブラリ.なお Java 8 以上じゃないと動かない.
どんなライブラリかというと,
- HTTP request を対象 URI に送り,それによって得られた response の内容をテストする為のラッパ的な機能を提供する
- response のテストが通ったら,その request と response の内容 (便宜上これを document としている) を所望の形式・方法で出力する
というライブラリ.要は HTTP request/response をテストしつつその内容をゲロっと吐くような機能を提供している.
つまりは貧者の autodoc と言い換えることが出来る.
詳しい使い方は README とか javadoc とかを見てもらうとして,実装上工夫している点としては以下の通り.
出力フォーマットをコントロールできる
出力フォーマットをコントロールできるというのは,response/request をどういうフォーマットで出力するかをコントロール出来るということ.
方法としては request と response の内容を任意のフォーマットに変換する formatter を出力する formatter generator を書いて (DocussFormatterGenerator
という Interface を実装する必要がある) それをコンストラクタに渡すことで出力フォーマットを制御できる.
先の autodoc は綺麗な markdown が出て格好良いのだけれど,個人的にそこまでのモチベーションが無かったのでデフォルトで提供している formatter generator は単に内容を YAML で吐き出すようになっている (ファイル追記とかを考えた時に YAML は単純に append できて楽,そして綺麗なドキュメントにしたければ YAML を解釈して任意の形式のドキュメントに落とすツールを書けば十分だと思ったという理由から).
もしも綺麗な markdown で出力したくなったらその時にその為の formatter generator を書けば良い.
出力方式をコントロールできる
出力方法をコントロールできるというのはつまり出力先を制御できるということで,出力フォーマットと同様に DocussPresenter
という Interface を実装することでコントロールが出来る.
デフォルトでは標準出力に吐く presenter と,ファイルに追記していくタイプの presenter を提供している.
特定の http client 実装に依存していない
特定の http client 実装に依存していないので,もし特定の http client を利用したい場合は DocussHttpClient
という Interface を実装して利用すれば良い.基本的に DocussHttpClient
の実装クラスがコアな責務を負っているという感じ.
デフォルトでは Apache httpclient のシンプルな実装を提供している (テスト用とだとそこまで凝った実装は必要ないだろう,という推測と現状から).
できるだけ特定のものに依存したくなくて,以上に挙げたようなものについては制御可能にすることで柔軟性を持たせた (と思っている).
まとめ
テストコードからドキュメント (的なもの) を生成するというのは流れとして自然というか正しいと思っていて,そういったもの,そしてシンプルなものが欲しかったので今回 Java 向けに書いた次第.
実コードを書いているとどうしても息切れをしてしまって,ドキュメントを書くところまで体力を保てないことがある.そうした中でもしっかりドキュメントを書けるように,こうしたサポートのツールは重要なのではないかと思っている.
気が向いたらどうぞお使いください.もうどんどん書いていくという精神になっている.
ここでオリジナルの autodoc author のありがたいお言葉を見てみましょう.
@moznion autodoc、発想が貧弱なMovableTypeなので、部分的に再生成とか差分を管理とか女々しいこと考え始めないほうが身のためです
— 協調 (@r7kamura) 2016年7月24日
@moznion 描画に異常な時間の掛かるテンプレートエンジンというイメージですね
— 協調 (@r7kamura) 2016年7月24日
以上です.