查看源代码 EEP-48：文档存储和格式
本用户指南描述了最初在EEP-48中描述的文档存储格式。通过标准化 API 文档的存储方式，将可以编写跨语言工作的工具。
要获取模块的 EEP-48 文档，请使用code:get_doc/1。
要呈现 Erlang 模块的 EEP-48 文档，请使用shell_docs:render/2。
“文档”存储
要查找名为example的模块的文档，工具应执行以下操作：
在代码路径中查找example.beam，解析 BEAM 文件，并检索Docs块。如果该块不可用，则应在代码路径中查找"example.beam"，并在定义example模块的应用程序中找到doc/chunks/example.chunk文件。如果不存在.chunk文件，则表示文档不可用。
选择使用块还是文件系统完全取决于语言或库。在这两种情况下，都可以随时通过删除Docs块（使用beam_lib）或删除doc/chunks目录来添加或删除文档。
例如，像 Elixir 和 LFE 这样的语言在编译时附加Docs块，这可以通过编译器标志来控制，而其他语言可能希望将文档生成与源代码编译分开进行。
“文档”格式
在这两种存储方式中，文档都以完全相同的格式编写：通过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）BeamLanguage- 表示语言的原子，例如：erlang、elixir、lfe、alpaca等Format- 文档的 MIME 类型，例如<<"text/markdown">>或<<"application/erlang+html">>。有关 Erlang 使用的格式的详细信息，请参阅 EDoc 用户指南中的EEP-48 章节。ModuleDoc- 以文档语言为键的映射，例如<<"en">>或<<"pt_BR">>，文档为二进制值。如果不存在文档，则可以为原子none，如果该条目的文档已被显式禁用，则可以为原子hidden。Metadata- 以原子键为键的映射，值可以是任何项。这可用于添加诸如模块的authors、deprecated或任何其他语言或文档工具认为相关的信息等注释。Docs- 模块中其他实体（例如函数和类型）的文档列表。
对于 Docs 中的每个条目，我们有：
{Kind, Name, Arity}- 标识函数、回调、类型等的种类、名称和元数。官方实体为：function、type和callback。其他语言将添加它们自己的。例如，Elixir 和 LFE 可能会添加macro。Anno- 模块文档或定义本身的注释（行、列、文件）（请参阅erl_anno）。Signature- 实体的签名。它是一个二进制列表。每个条目表示签名中的一个二进制，可以使用空格或换行符连接。例如，[<<"binary_to_atom(Binary, Encoding)">>, <<"when is_binary(Binary)">>]可以呈现为单行或两行。它的存在仅用于展示目的。Doc- 以文档语言为键的映射，例如<<"en">>或<<"pt_BR">>，文档为值。文档可以是二进制文件或任何 Erlang 项，两者都由Format描述。如果是 Erlang 项，则Format必须是<<"application/erlang+SUFFIX">>，例如当文档是 HTML 文档的 Erlang 表示时为<<"application/erlang+html">>。Doc也可以是原子none（如果不存在文档）或原子hidden（如果该条目的文档已被显式禁用）。Metadata- 以原子键为键的映射，值可以是任何项。
这种共享格式是 EEP 的核心，因为它有效地实现了跨语言协作。
元数据字段的存在是为了允许语言、工具和库向每个条目添加自定义信息。此 EEP 文档记录了以下元数据键：
authors := [binary()]- 作者列表，为二进制数据。cross_references := [module() | {module(), {Kind, Name, Arity}}]- 可用作生成文档时的交叉引用的模块或模块条目列表。deprecated := binary()- 如果存在，则表示当前条目已弃用，二进制数据表示弃用原因以及替换已弃用代码的建议。since := binary()- 表示添加该条目的版本的二进制数据，例如<<"1.3.0">>或<<"20.0">>。edit_url := binary()- 表示更改文档本身的 URL 的二进制数据。
可以随时将任何键添加到元数据。社区经常使用的键可以在未来的版本中进行标准化。