ドキュメント の

ドキュメントについて

Elixirのドキュメントは：

• 第一級の存在です。
• Markdownで書きます。
• 特別なモジュール属性を使って追加します。
• 複数行の文字列には、通常ヒアドキュメント構文を使います。

ドキュメントに使うモジュール属性：

• @moduledoc：モジュールを説明します。モジュールの最初の行に書きます。
• @doc：関数を説明します。関数の定義と型仕様のすぐ上に書きます。
• @typedoc：カスタム型を説明します。型の定義のすぐ上に書きます。

defmodule String do
  @moduledoc """
  Strings in Elixir are UTF-8 encoded binaries.
  """

  @typedoc """
  A UTF-8 encoded binary.
  """
  @type t :: binary

  @doc """
  Converts all characters in the given string to uppercase according to `mode`.

  ## Examples

      iex> String.upcase("abcd")
      "ABCD"

      iex> String.upcase("olá")
      "OLÁ"
  """
  def upcase(string, mode \\ :default)
end

ドキュメントとコードコメントの違い

Elixirは、ドキュメントとコードコメントを別々の概念として扱います。

ドキュメントは、公開APIの利用者との間で交わす明示的な契約です（同僚や未来の自分も利用者に含まれます）。利用者がソースコードを読めるとは限らないので、ドキュメントでコードの使い方を説明します。

コードコメントは、ソースコードを読むエンジニアに向けたものです。メモを残したり、実装の詳細を説明したり、改善の余地を示したりするのに役立ちます。

ドキュメントはコードの公開APIを説明するものなので、プライベート関数に@doc属性を付けようとすると、コンパイル警告が出ます。プライベート関数の説明には、代わりにコードコメントを使います。

warning: defp do_check_length/2 is private, @doc attribute is always discarded for private functions/macros/types
  lib/form.ex:33: Form.do_check_length/2

ドキュメントを読む

Elixirプロジェクトのドキュメントにアクセスする方法は、たくさんあります。

hexdocs.pmとExDoc

hex.pmは、ElixirとErlangのパッケージリポジトリです。hex.pmに公開されたパッケージは、ドキュメントも自動的にhexdocs.pmに公開されます。そこでは、お気に入りのElixirライブラリのドキュメントはもちろん、Elixirの公式ドキュメントも見つかります。

hex.pmにパッケージを公開しなくても、Elixirの公式ドキュメントと同じ見た目のドキュメントサイトを自分のプロジェクト用に生成できます。そのためのツールがExDocです。ExDocは、ローカルのファイルシステムから閲覧できるHTMLファイルを生成します。

ExDocを最高の結果で使うために、ドキュメントを書くための公式の推奨事項に従いましょう。

IExのhヘルパー

標準ライブラリやインストール済みのライブラリ、そして自分のElixirプロジェクトのドキュメントに、自分のコンピューターから直接アクセスできます。

コンピューターにElixirがインストールされていれば、iexコマンドを実行して対話モードで使えます（現在のmixプロジェクトのソースを読み込みたい場合はiex -S mixです）。

iexでは、hに続けてスペースとモジュール名または関数名を入力すると、そのドキュメントを読めます。

iex()> h String.upcase/1
# def upcase(string, mode \\ :default)
#
# Converts all characters in the given string to uppercase according to mode.
# (...)

モジュール名や関数名を途中まで入力してからTabキーを押すと、オートコンプリートで利用できるモジュールや関数を見つけられます。

最近のIDE

Elixirをサポートする最近のIDEの多くは、ドキュメントや型仕様を解析して、便利なポップアップで表示できます。たとえばVisual Studio CodeやElixirプラグインを入れたIntellijなどです。

内部モジュールと関数

モジュールや関数を内部での利用だけを目的とする場合は、@moduledoc falseまたは@doc falseを付けます。それらのモジュールと関数は、生成されるドキュメントに含まれません。ただし、これでプライベートになるわけではありません。呼び出したりインポートしたりすることはできます。この問題への対処法については、内部モジュールと関数を隠す方法についての公式ドキュメントを確認してください。