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で読みやすくなる。