9 EEP-48: Erlang/OTP 中的实现
9.1 EEP-48: 文档存储和格式
EEP-48 定义了 Erlang/OTP 生态系统中模块文档的通用文档存储格式。Erl_Docgen 可以根据此应用程序中其他用户指南中描述的 DTD 从 XML 文件生成此格式的文档。
在编写也应通过 EEP-48 样式存储提供的文档时，需要考虑一些特殊情况。
- #PCDATA 在 <name> 标签中必须可解析，以便确定函数的元数。
- 不允许将 <name> 标签与 #PCDATA 和属性混合使用。
- 所有 <name> 标签在 <func> 中必须具有 since 属性。
- 所有回调函数文档都必须以 Module 前缀开头。
9.2 Erlang 文档格式
为 EEP-48 生成文档时，Erl_Docgen 使用格式 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 文档格式进行验证。
9.3 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
- 与该函数关联的 spec AST。它用于渲染文档条目更具描述性的口号。
- equiv := {Type,Name,Arity}
- 当前函数/类型与另一个函数/类型共享文档。这意味着，如果要同时显示此函数/类型和目标函数/类型，则应仅显示此函数/类型的原型，而文档将使用一个通用的文本主体。