Elixir Writing Docs

Quick Reference

Topic	Reference
Doctests: syntax, gotchas, when to use	references/doctests.md
Cross-references and linking syntax

references/cross-references.md | | Admonitions, formatting, tabs | references/admonitions-and-formatting.md |

First-Line Summary Rule

ExDoc and tools like mix docs extract the first paragraph of @moduledoc and @doc as a summary. Keep the opening line concise and self-contained.

CODEBLOCK0

The same rule applies to @doc:

CODEBLOCK1

@moduledoc Structure

A well-structured @moduledoc follows this pattern:

CODEBLOCK2

Key points:

- First paragraph is the summary (one to two sentences).
INLINECODE5 shows realistic usage. Use doctests when the example is runnable.
INLINECODE6 documents required config keys. Omit this section if the module takes no config.
Use second-level headings (##) only. First-level (#) is reserved for the module name in ExDoc output.

Documenting Behaviour Modules

When defining a behaviour, document the expected callbacks:

CODEBLOCK3

@doc Structure

CODEBLOCK4

Guidelines:

- State what the function does, then what it returns.
Document each option in a bulleted ## Options section when the function accepts a keyword list.
Place @spec between @doc and def. This is the conventional ordering.
Include doctests for pure functions. Skip them for side-effecting functions (see references/doctests.md).

@typedoc

Document custom types defined with @type or @opaque:

CODEBLOCK5

For @opaque types, the @typedoc is especially important because callers cannot inspect the structure.

Metadata

@doc since and @doc deprecated

CODEBLOCK6

You can combine metadata and the docstring in one attribute:

CODEBLOCK7

INLINECODE17 works the same way for modules:

CODEBLOCK8

When to Use @doc false / @moduledoc false

Suppress documentation when the module or function is not part of the public API:

CODEBLOCK9

Do NOT use @doc false on genuinely public functions. If a function is exported and callers depend on it, document it. If it should not be called externally, make it private with defp.

Documentation vs Code Comments

	Documentation (`@moduledoc`, `@doc`)	Code Comments (`#`)
Audience	Users of your API	Developers reading source
Purpose

CODEBLOCK10

The @doc tells the caller what validate_coupon/1 does and returns. The inline comment explains an implementation decision that would otherwise be surprising.

When to Load References

- Writing doctests or debugging doctest failures --> references/doctests.md
Adding links between modules, functions, types --> references/cross-references.md
Using admonition blocks, tabs, or formatting in docs --> references/admonitions-and-formatting.md

Elixir 编写文档

快速参考

主题	参考
文档测试：语法、注意事项、使用时机	references/doctests.md
交叉引用和链接语法

references/cross-references.md | | 提示块、格式、标签页 | references/admonitions-and-formatting.md |

首行摘要规则

ExDoc 和 mix docs 等工具会提取 @moduledoc 和 @doc 的第一段作为摘要。请保持首行简洁且独立完整。

elixir

正确 - 首行可作为独立摘要使用

@moduledoc
通过 Stripe 和本地账本对账处理支付。

封装 Stripe API 客户端，确保在向调用方返回确认之前，每笔费用都已记录在本地账本中。

错误 - 首行表述模糊，迫使读者继续阅读

@moduledoc 本模块包含与支付相关的各种函数。

它使用 Stripe 并同时更新账本。

同样的规则适用于 @doc：

elixir

正确

@doc
以分为单位，向客户的默认支付方式收取指定金额。

成功时返回 {:ok, charge}，支付网关拒绝请求时返回 {:error, reason}。

错误

@doc 此函数用于向客户收费。

@moduledoc 结构

一个结构良好的 @moduledoc 遵循以下模式：

elixir
defmodule MyApp.Inventory do
@moduledoc
跟踪仓库库存水平并触发补货订单。

本模块维护一个基于 ETS 的当前数量缓存，并暴露用于原子库存调整的函数。
设计在监督器下启动，并在初始化时从数据库恢复状态。

## 示例

iex> {:ok, pid} = MyApp.Inventory.start_link(warehouse: :east)
iex> MyApp.Inventory.current_stock(pid, SKU-1042)
{:ok, 350}

## 配置

在 config/runtime.exs 中期望以下配置：

config :my_app, MyApp.Inventory,
repo: MyApp.Repo,
lowstockthreshold: 50

end

关键点：

- 第一段是摘要（一到两句话）。
## 示例展示实际用法。当示例可运行时，使用文档测试。
## 配置记录所需的配置键。如果模块不需要配置，则省略此部分。
仅使用二级标题（##）。一级标题（#）在 ExDoc 输出中保留给模块名称。

记录行为模块

在定义行为时，记录预期的回调：

elixir
defmodule MyApp.PaymentGateway do
@moduledoc
支付网关集成的行为。

实现必须处理收费、退款和状态检查。
请参阅 MyApp.PaymentGateway.Stripe 获取参考实现。

## 回调

* charge/2 - 发起指定金额的收费
* refund/2 - 退款先前完成的收费
* status/1 - 检查交易状态

@callback charge(amount :: pos_integer(), currency :: atom()) ::
{:ok, transaction_id :: String.t()} | {:error, term()}

@callback refund(transactionid :: String.t(), amount :: posinteger()) ::
:ok | {:error, term()}

@callback status(transaction_id :: String.t()) ::
{:pending | :completed | :failed, map()}
end

@doc 结构

elixir
@doc
预留指定数量的物品，减少可用库存。

当库存可用时返回 {:ok, reservation_id}，当请求数量超过现有库存时返回
{:error, :insufficient_stock}。

示例

iex> MyApp.Inventory.reserve(SKU-1042, 5)
{:ok, res_abc123}

iex> MyApp.Inventory.reserve(SKU-9999, 1)
{:error, :not_found}

选项

* :warehouse - 目标仓库原子。默认为 :primary。
* :timeout - 超时时间（毫秒）。默认为 5_000。

@spec reserve(String.t(), pos_integer(), keyword()) ::
{:ok, String.t()} | {:error, :insufficientstock | :notfound}
def reserve(sku, quantity, opts \\ []) do
# ...
end

指南：

- 说明函数的功能，然后说明其返回值。
当函数接受关键字列表时，在带项目符号的 ## 选项部分中记录每个选项。
将 @spec 放在 @doc 和 def 之间。这是常规顺序。
为纯函数包含文档测试。为有副作用的函数跳过文档测试（请参阅 references/doctests.md）。

@typedoc

记录使用 @type 或 @opaque 定义的自定义类型：

elixir
@typedoc
表示最小货币单位（例如，分）金额的正整数。

@type amount :: pos_integer()

@typedoc
由 status/1 返回的预留状态。

* :held - 库存已预留但尚未发货
* :released - 预留已取消，库存已恢复
* :fulfilled - 物品已发货

@type reservation_status :: :held | :released | :fulfilled

@typedoc
由 connect/1 返回的不透明句柄。请勿对此值进行模式匹配。

@opaque connection :: %MODULE{socket: port(), buffer: binary()}

对于 @opaque 类型，@typedoc 尤其重要，因为调用方无法检查其结构。

元数据

@doc since 和 @doc deprecated

elixir
@doc since: 1.3.0
@doc
在两个仓库之间转移库存。

def transfer(from, to, sku, quantity), do: # ...

@doc deprecated: 请改用 transfer/4
@doc
在位置之间移动物品。已弃用，请改用支持跨区域转移的 transfer/4。

def move_stock(from, to, sku, quantity), do: # ...

可以在一个属性中组合元数据和文档字符串：

elixir
@doc since: 2.0.0, deprecated: 请改用 bulk_reserve/2
@doc
在单次调用中预留多个物品。

def batch_reserve(items), do: # ...

@moduledoc since: 对模块的工作方式相同：

elixir
@moduledoc since: 1.2.0
@moduledoc
处理 Stripe 事件的 Webhook 签名验证。

何时使用 @doc false / @moduledoc false

当模块或函数不属于公共 API 时，抑制文档：

elixir

私有实现模块 — 应用程序内部使用

defmodule MyApp.Inventory.StockCache do
@moduledoc false
# ...
end

协议实现 — 在协议级别记录

defimpl String.Chars, for: MyApp.Money do @moduledoc false # ... end

回调实现 — 在行为级别记录

@doc false def handle_info(:refresh, state) do # ... end

仅在模块内部使用的辅助函数

@doc false def do_format(value), do: # ...

不要在真正的公共函数上使用 @doc false。 如果函数被导出且调用方依赖它，请为其编写文档。如果不应该被外部调用，请使用 defp 将其设为私有。

文档与代码注释

	文档（@moduledoc、@doc）	代码注释（#）
受众	API 的用户	阅读源代码的开发者
目的

elixir
@doc
验证给定的优惠券代码是否处于激活状态且还有剩余使用次数。

@spec validate_coupon(String.t()) :: {:ok, Coupon.t()} | {:error, :expired | :exhausted}
def validate_coupon(code) do
# 我们在此处查询只读副本，以避免在高

elixir-writing-docsElixir文档编写