Julia のドキュメント生成

Posted at 2019-12-22

まえおき

Julia に関しては全く初心者でこんなブックマークを週１回ペースで更新するくらいのことしかしていません。

オブジェクト指向の言語の API を読みなれていたので Java の Javadoc や Ruby の yard のような形式のドキュメントが Julia でも読めると良いなと思って今回ちょっと試行錯誤してみました。

欲しいのは特定の type について、type で使えるすべての function の説明がなされているようなもの(つまり API 一覧)です。

type T で使える function 一覧は、

  methodswith(T)

で得られます。

一方、function foo に付されている docstring は、

 @doc foo

で得られます¹。

ドキュメント生成はこの２つを組み合わせておこなうことができます。

例えば type Array を使う API 一覧なら REPL 上で、

  s = Set()
  for m in methodswith(Array, supertypes=true)
    if !in(m.name, s)
      println("@doc $(m.name)")
      push!(s, m.name)
    end
  end

のようなスクリプトを動かして、

  @doc sparsevec
  @doc serialize
  @doc /
    …
  @doc launch

のようなアウトプットを出し、これを一旦クリップボードに取り込んだ後、REPL にペーストすればよい。

@doc は function ではなく macro なので、

    println("@doc $(m.name)")

のところを、

    @doc m.name

のように書いてもうまくいきません。@doc に渡されるのが m.name の値ではなく構文だからです。

今回の課題はメタプログラミングに詳しい方ならもっとスマートに自動化できそうなのでご指導いただければと思います。