檢視原始碼 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">>。文件內容是代表類似 HTML 結構的 Erlang 項。
-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}- 目前的函數/類型與另一個函數/類型共享文件。這表示如果此函數/類型和目標函數/類型同時顯示，則只會顯示此函數/類型的原型，並且文件將使用共同的本文。