読者です 読者をやめる 読者になる 読者になる

その手の平は尻もつかめるさ

ギジュツ的な事をメーンで書く予定です

Docuss というテストとドキュメント出力を一緒にやるライブラリ書いた

java

Docuss というものを書いた.Java のライブラリ.なお Java 8 以上じゃないと動かない.

どんなライブラリかというと,

  • HTTP request を対象 URI に送り,それによって得られた response の内容をテストする為のラッパ的な機能を提供する
  • response のテストが通ったら,その request と response の内容 (便宜上これを document としている) を所望の形式・方法で出力する

というライブラリ.要は HTTP request/response をテストしつつその内容をゲロっと吐くような機能を提供している.
つまりは貧者の autodoc と言い換えることが出来る.


詳しい使い方は README とか javadoc とかを見てもらうとして,実装上工夫している点としては以下の通り.

  • 出力フォーマットをコントロールできる
  • 出力方法をコントロールできる
  • 特定の http client 実装に依存していない
出力フォーマットをコントロールできる

出力フォーマットをコントロールできるというのは,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 のありがたいお言葉を見てみましょう.

以上です.