查看源代码 EEP-48：在 Erlang/OTP 中的实现
EEP-48：文档存储和格式
EEP-48 为 Erlang/OTP 生态系统中的模块文档定义了一种通用的文档存储格式。Erl_Docgen 可以从 XML 文件中生成此格式的文档，这些 XML 文件遵循此应用程序其他用户指南中描述的 DTD。
在编写也应通过 EEP-48 样式存储提供的文档时，需要考虑一些特殊事项。
Erlang 文档格式
在为 EEP-48 生成文档时，edoc 使用 mime 类型 <<"application/erlang+html">>。文档内容是一个 Erlang 术语，它表示类似 HTML 的结构。
-type chunk_elements() :: [chunk_element()].
-type chunk_element() :: {chunk_element_type(),chunk_element_attrs(),
chunk_elements()} | unicode:unicode_binary().
-type chunk_element_attrs() :: [chunk_element_attr()].
-type chunk_element_attr() :: {atom(),unicode:unicode_binary()}.
-type chunk_element_type() :: chunk_element_inline_type() | chunk_element_block_type().
-type chunk_element_inline_type() :: a | code | strong | b | em | i.
-type chunk_element_block_type() :: p | 'div' | br | pre | ul |
ol | li | dl | dt | dd |
h1 | h2 | h3 | h4 | h5 | h6.不同的元素类型在呈现时遵循其 HTML 含义。以下是一些关于如何允许生成块元素的一般规则。
- 内联和
pre元素不允许包含块元素。 p元素不允许嵌套。
某些元素的属性具有特殊含义。
{'div',[{class,unicode:unicode_binary()}],_}- 类名将用于为 div 中的内容提供样式。Erlang/OTP 使用的类类型包括：warning、note、do、dont和quote。{ul,[{class,<<"types">>}],_}- 这是包含类型文档的列表。{li,[{name,TypeName :: unicode:unicode_binary()}],_}- 带有类型规范的列表项，该类型规范位于此模块 EEP-48 文档的元数据中。实现应在types键下查找类型的 AST 表示。此属性仅在类为 <<"types">> 的ul下有效。{li,[{class,<<"type">>}],_}- 具有以 Erlang 文档格式描述的类型的列表项。此属性仅在类为 <<"types">> 的ul下有效。{li,[{class,<<"description">>}],_}- 列表中的前一个类型的描述的列表项。此属性仅在类为 <<"types">> 的ul下有效。
可以使用 shell_docs:validate/1 函数来验证 Erlang 文档格式。
Erlang 文档额外元数据
Erlang/OTP 使用一些额外的元数据字段将更多信息嵌入到 EEP-48 文档中。
模块级别的字段
otp_doc_vsn := {non_neg_integer(),non_neg_integer(),non_neg_integer()}- 描述此模块中使用的 Erlang 文档格式的版本types := #{ TypeName :: unicode:unicode_binary() => TypeAST }- 一个包含属于此模块的类型的 AST 的映射。此映射由函数和回调使用，以便将类型内联呈现到其文档中。
函数和类型的字段
signature := SpecAST- 与此函数关联的规范 AST。它用于为文档条目呈现更具描述性的标语。equiv := {Type,Name,Arity}- 当前函数/类型与另一个函数/类型共享文档。这意味着如果此函数/类型和目标函数/类型同时显示，则仅会显示此函数/类型的原型，并且文档将使用公共文本主体。