檢視原始碼 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 區塊，這可以通過編譯器標誌來控制，而其他語言可能希望將文件生成與原始碼的編譯分開。
「文件」格式
在這兩種儲存方式中，文件都以完全相同的格式編寫：一個 Erlang 項，通過 term_to_binary/1 序列化為二進位。序列化時，該項可以選擇性地壓縮。它必須遵循以下類型規範
{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 的核心，因為它有效地允許跨語言協作。
Metadata 欄位允許語言、工具和函式庫將自訂資訊新增到每個項目。此 EEP 記錄了以下 metadata 鍵
authors := [binary()]- 作為二進位的作者清單。cross_references := [module() | {module(), {Kind, Name, Arity}}]- 模組或模組項目的清單，可用於生成文件時的交叉參考。deprecated := binary()- 如果存在，則表示目前的項目已棄用，二進位表示棄用的原因以及取代棄用程式碼的建議。since := binary()- 表示新增此項的版本之二進位，例如<<"1.3.0">>或<<"20.0">>。edit_url := binary()- 表示變更文件本身之 URL 的二進位。
可以隨時將任何鍵新增至 Metadata。社群經常使用的鍵可以在未來版本中標準化。