文档 属于

关于 文档

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 官方文档本身。

无需把包发布到hex.pm，你也能为自己的项目生成一个文档网站，外观和 Elixir 官方文档一模一样。完成这项工作的工具叫做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标记它。这些模块和函数不会包含在生成的文档中。请注意，这并不会让它们变成私有的，它们仍然可以被调用或导入。关于这个问题的潜在解决办法，请查阅隐藏内部模块和函数的官方文档。