文件 在

關於 文件

Elixir 的說明文件：

• 是一等公民。
• 以Markdown撰寫。
• 透過特殊的模組屬性加入。
• 多行字串通常使用 heredoc 語法。

用於說明文件的模組屬性：

• @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 官方說明文件本身。

你可以為自己的專案產生一個與 Elixir 官方說明文件長得一模一樣的說明網站，而不必把套件發佈到hex.pm。負責這件事的工具叫做 ExDoc。ExDoc會產生 HTML 檔案，讓你可以直接從本機的檔案系統瀏覽。

使用ExDoc時，請務必遵循官方撰寫說明文件的建議，以確保獲得最佳成果。

h IEx 輔助工具

你可以直接從自己的電腦取用標準函式庫、任何你安裝的函式庫，以及你的 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標記它。這些模組和函式不會被收錄到產生的說明文件裡。請注意，這並不會讓它們變成私有。它們仍然可以被呼叫或匯入。想知道這個問題有哪些可能的解決方式，請參閱關於隱藏內部模組與函式的官方說明文件。