Elixirでドキュメントのテストを書く

結論

https://hexdocs.pm/elixir/Code.html#fetch_docs/1を使えばできる。

前提

以下を題材にします。

defmodule MyModule do
  @moduledoc "モジュールの説明"

  @doc "関数の説明"
  def my_fun do
  end
end

@moduledocや@docに期待した内容が書かれているかテストを書いておきたいときどうしましょうかって話。普通にドキュメントを書いた場合はそれってテストとして意味あるんですかって感じですが、マクロで関数定義してるときに一緒にドキュメントも生成している場合なんかを想定しています。

どうする

ドキュメントを文字列で取れればあとは煮るなり焼くなり。Code.fetch_docs/1で取れます。

iex(1)> Code.fetch_docs MyModule
{:docs_v1, 2, :elixir, "text/markdown", %{"en" => "モジュールの説明"},
 %{},
 [{{:function, :my_fun, 0}, 4, ["my_fun()"], %{"en" => "関数の説明"}, %{}}]}

あとはパターンマッチとか駆使して欲しい物を拾っていただければOK。moduledocはModule.get_attribute/2でも取れそうですけど、コンパイル後は取得できないので注意。

ちょっと違う選択肢としては、ドキュメント組み立てるマンをつくってそれのテストを書くってのもあり。本当にそれが@docにあるかは分からないけど。

@doc MyModule.Document.build(...)
def my_fun do
end