今日のElixirSchoolメモ11「ドキュメント」 #Elixir

Elixir Schoolの勉強メモです。

注釈

Elixirはドキュメントを第1級市民として扱い、プロジェクトのドキュメントにアクセスしたり、生成したりするための各種の関数を用意している。

# インラインドキュメント用
@moduledoc モジュールレベルのドキュメント用
@doc　関数レベルのドキュメント用

インラインドキュメント

# コンソールに 'Hello, chum.' と出力します。
IO.puts "Hello, " <> "chum."

モジュールレベルのドキュメント

@moduledocアノテータはインラインドキュメントをモジュール単位で行うためのもの。
通常はファイル最上部でdefmoduleの宣言を直後に置かれる。

defmodule Greeter do
  @moduledoc """
  ある人を歓迎する `hello/1` 関数を提供します
  """

  def hello(name) do
    "Hello, " <> name
  end
end

モジュールドキュメントは、IEx内でhヘルパー関数を用いてアクセスできる。
Greeterモジュールを新しいファイルgreeter.exに入れてコンパイルすると、
これを自分で確認できる。

iex(1)> c("greeter.ex", ".")
[Greeter]
iex(2)> h Greeter

                                    Greeter

ある人を歓迎する hello/1 関数を提供します

関数のドキュメント化

@docアノテータは関数レベルでのインラインドキュメントを行うためのもの。
注釈をつけたい関数の直前に置かれる。

ExDoc

ExDoxは公式のElixirプロジェクト。
ExDocはHTMLとオンラインドキュメントを生成する。

最初にアプリケーションのためにMixプロジェクトを生成する。

$ mix new greet_everyone

* creating README.md
* creating .gitignore
* creating .formatter.exs
* creating mix.exs
* creating lib
* creating lib/greet_everyone.ex
* creating test
* creating test/test_helper.exs
* creating test/greet_everyone_test.exs

Your Mix project was created successfully.
You can use "mix" to compile it, test it, and more:

    cd greet_everyone
    mix test

Run "mix help" for more commands.

$ cd greet_everyone

lib/greeter.exファイルを保存し、コマンドラインから動作を確認する。
iex -S mixコマンドで起動する。

iex(2)> h Greeter.hello

                                def hello(name)

  @spec hello(String.t()) :: String.t()

Helloメッセージを表示します

## パラメータ

  • name: 人名を表現する文字です。

## 例

    iex> Greeter.hello("Sean")
    "Hello, Sean"

    iex> Greeter.hello("pete")
    "Hello, pete"

インストール

全てがうまくいったらExDocの環境構築が準備できていることを意味します。
mix.exsファイルに :ex_docの依存関係を追加します。

def deps do
  [{:ex_doc, "~> 0.21", only: :dev, runtime: false}]
end

only: :devというキーバリューのペアを指定することで、
本番環境では:ex_docの依存関係パッケージをダウンロードしたりコンパイルしあいようにしたりする。

ex_docはEarmarkという別のライブラリも追加する。

Earmarkは、Exdocが@moduledocおよび@doc内のドキュメントを美しいHTMLに変換するために使用するElixirプログラミング言語用のMarkdownパーサー。

ドキュメント生成

コマンドラインから2つのコマンドを実行する。

$ mix deps.get # ExDocとEarmarkを取得する
$ mix docs # ドキュメントを作成する
Generating docs...
View "html" docs at "doc/index.html"
View "epub" docs at "doc/greet_everyone.epub"

doc/ディレクトリにある生成されたドキュメントを見てみます。

これでGithubや自身のWebサイト、HexDocsへデプロイできるようになります。

ベストプラクティス

モジュールには常にドキュメントを書く。
だが、モジュールのドキュメントを書くつもりが無い場合は、空のままにせずfalseの注釈をつける。

defmodule Greeter do
  @moduledoc false

end

また、@docなどの関数内でmarkdownを使うと、IExやExDocで読みやすくなる。