5 EEP-48: 文档存储和格式

本用户指南描述了最初在 EEP-48 中描述的文档存储格式。通过标准化 API 文档的存储方式，可以编写跨语言工作的工具。

要获取模块的 EEP-48 文档，可以使用 code:get_doc/1。

要渲染 Erlang 模块的 EEP-48 文档，可以使用 shell_docs:render/2。

5.1 “文档”存储

要查找模块名称示例的文档，工具应该

在代码路径中查找 example.beam，解析 BEAM 文件并检索 Docs 块。如果块不可用，它应该在代码路径中查找“example.beam”并在定义 example 模块的应用程序中找到 doc/chunks/example.chunk 文件。如果 .chunk 文件不可用，则文档不可用。

使用块或文件系统完全取决于语言或库。在这两种情况下，都可以通过剥离 Docs 块或删除 doc/chunks 目录来随时添加或删除文档。

例如，像 Elixir 和 LFE 这样的语言在编译时附加 Docs 块，这可以通过编译器标志来控制。另一方面，像 OTP 本身这样的项目可能会在与代码编译无关的单独命令上生成 doc/chunks 条目。

5.2 “文档”格式

在两种存储中，文档都以完全相同的格式编写：通过 term_to_binary/1 序列化为二进制的 Erlang 项。在序列化时，该项可以可选地进行压缩。它必须遵循下面的类型规范

{docs_v1,
 Anno :: erl_anno:anno(),
 BeamLanguage :: atom(),
 Format :: binary(),
 ModuleDoc :: #{DocLanguage := DocValue} | none | hidden,
 Metadata :: map(),
 Docs ::
   [{{Kind, Name, Arity},
     Anno :: erl_anno:anno(),
     Signature :: [binary()],
     Doc :: #{DocLanguage := DocValue} | none | hidden,
     Metadata :: map()
    }]} when DocLanguage :: binary(),
             DocValue :: binary() | term()

其中，在根元组中，我们有

Anno: 定义本身的注释（行、列、文件）（参见 erl_anno(3)）
BeamLanguage: 表示语言的原子，例如：erlang、elixir、lfe、alpaca 等
Format: 文档的 MIME 类型，例如 <<"text/markdown">> 或 <<"application/erlang+html">>。有关 Erlang 使用的格式的详细信息，请参阅 Erl_Docgen 用户指南中的 EEP-48 章节。
ModuleDoc: 一个以文档语言为键的映射，例如 <<"en">> 或 <<"pt_BR">>，以及文档作为二进制值。如果没有任何文档，它可能是原子 none，如果已明确禁用此条目的文档，则可能是原子 hidden。
Metadata: 一个以原子键为键、以任何项为值的映射。这可以用于添加注释，例如模块的 authors、deprecated，或任何其他语言或文档工具可能认为相关的注释。
Docs: 模块中其他实体（如函数和类型）的文档列表。

对于 Docs 中的每个条目，我们都有

{Kind, Name, Arity}: 标识函数、回调、类型等的种类、名称和元数。官方实体是：function、type 和 callback。其他语言将添加自己的实体。例如，Elixir 和 LFE 可能会添加宏。
Anno: 模块文档或定义本身的注释（行、列、文件）（参见 erl_anno(3)）。
Signature: 实体的签名。它是一个二进制列表。每个条目代表签名中的一个二进制，可以使用空格或换行符连接起来。例如，[<<"binary_to_atom(Binary, Encoding)">>, <<"when is_binary(Binary)">>] 可以渲染为一行或两行。它仅出于展示目的存在。
Doc: 一个以文档语言为键的映射，例如 <<"en">> 或 <<"pt_BR">>，以及文档作为值。文档可以是二进制或任何 Erlang 项，两者都由 Format 描述。如果它是 Erlang 项，则 Format 必须为 <<"application/erlang+SUFFIX",>>，例如 <<"application/erlang+html">>，当文档是 HTML 文档的 Erlang 表示时。Doc 也可以是原子 none，如果没有任何文档，或者原子 hidden，如果已明确禁用此条目的文档。
Metadata: 一个以原子键为键、以任何项为值的映射。

这种共享格式是 EEP 的核心，因为它实际上允许跨语言协作。

Metadata 字段允许语言、工具和库为每个条目添加自定义信息。本 EEP 文档以下元数据键

authors := [binary()]: 一个以二进制表示的作者列表。
cross_references := [module() | {module(), {Kind, Name, Arity}}]: 一个模块或模块条目的列表，这些模块或模块条目可以用作生成文档时的交叉引用。
deprecated := binary(): 如果存在，则表示当前条目已弃用，并使用二进制表示弃用原因以及替换已弃用代码的建议。
since := binary(): 一个表示添加此条目的版本的二进制，例如 <<"1.3.0">> 或 <<"20.0">>。
edit_url := binary(): 一个表示更改文档本身的 URL 的二进制。

任何键都可以随时添加到 Metadata 中。社区经常使用的键可以在将来的版本中进行标准化。

5.3 另请参阅

erl_anno(3)，shell_docs(3)，Erl_Docgen 用户指南中的 EEP-48 章节，code:get_doc/1