<div dir="ltr">Thank you Raimo! I have sent a PR based on the discussion in this mailing list: <a href="https://github.com/erlang/eep/pull/5">https://github.com/erlang/eep/pull/5</a><div><br></div><div><br></div></div><div class="gmail_extra"><br clear="all"><div><div class="gmail_signature" data-smartmail="gmail_signature"><div dir="ltr"><div><div><br></div><div><br></div><span style="font-family:arial,sans-serif;font-size:13px;border-collapse:collapse"><b><span style="border-collapse:separate;font-family:arial;font-weight:normal"><div><span style="font-family:arial,sans-serif;font-size:13px;border-collapse:collapse"><b>José Valim</b></span></div><div><span style="font-family:arial,sans-serif;font-size:13px;border-collapse:collapse"><div><span style="font-family:verdana,sans-serif;font-size:x-small"><a href="http://www.plataformatec.com.br/" style="color:rgb(42,93,176)" target="_blank">www.plataformatec.com.br</a></span></div><div><span style="font-family:verdana,sans-serif;font-size:x-small">Founder and </span><b><span style="border-collapse:separate;font-family:arial;font-weight:normal"><div style="display:inline!important"><span style="font-family:verdana,sans-serif;font-size:x-small">Director of R&D</span></div></span></b></div></span></div></span></b></span></div></div></div></div>
<br><div class="gmail_quote">On Wed, Jan 10, 2018 at 4:47 PM, Raimo Niskanen <span dir="ltr"><<a href="mailto:raimo+eeps@erix.ericsson.se" target="_blank">raimo+eeps@erix.ericsson.se</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">I have added your proposal to the repository as EEP 48:<br>
<br>
<a href="http://erlang.org/eep/eeps/eep-0048.html" rel="noreferrer" target="_blank">http://erlang.org/eep/eeps/<wbr>eep-0048.html</a><br>
<a href="https://github.com/erlang/eep/blob/master/eeps/eep-0048.md" rel="noreferrer" target="_blank">https://github.com/erlang/eep/<wbr>blob/master/eeps/eep-0048.md</a><br>
<br>
I changed the quoting of atoms and pathnames to use `code` quoting,<br>
changed some strange double and single quote characters into the ASCII<br>
ones, and set José as the main author partly because of him sending in the<br>
EEP gave me an e-mail address to use obfuscated and partly because he<br>
declared the others as co-authors.<br>
<br>
Thank you for your contribution!<br>
<br>
/ Raimo Niskanen, EEP editor.<br>
<br>
<br>
<br>
On Thu, Jan 04, 2018 at 10:59:58PM +0100, José Valim wrote:<br>
> This EEP proposes an official API documentation storage to be used by<br>
> by BEAM languages. By standardizing how API documentation is stored,<br>
> it will be possible to write tools that work across languages.<br>
><br>
> I want to thank Eric and Radek, who co-authored the proposal, as well as<br>
> Kenneth, Fred, Tristan and Loïc for their feedback.<br>
><br>
> See the attached document.<br>
><br>
> *José <a href="http://Valimwww.plataformatec.com.br" rel="noreferrer" target="_blank">Valimwww.plataformatec.com.br</a><br>
> <<a href="http://www.plataformatec.com.br/" rel="noreferrer" target="_blank">http://www.plataformatec.com.<wbr>br/</a>>Founder and Director of R&D*<br>
<br>
> Author: Eric Bailey, Radek Szymczyszyn, José Valim<br>
> Status: Draft<br>
> Type: Standards Track<br>
> Created: 04-Jan-2018<br>
> Post-History:<br>
> ****<br>
> EEP XX: Documentation storage and format<br>
> ----<br>
><br>
><br>
><br>
> Abstract<br>
> ========<br>
><br>
> This EEP proposes an official API documentation storage to be used by<br>
> by BEAM languages. By standardizing how API documentation is stored,<br>
> it will be possible to write tools that work across languages.<br>
><br>
><br>
><br>
> Rationale<br>
> =========<br>
><br>
> Currently, different programming languages and libraries running on<br>
> BEAM devise their own schemas for storing and accessing documentation.<br>
> For example, Elixir and LFE provide a `h` helper in their shell that<br>
> can print the documentation of any module:<br>
><br>
> iex> h String<br>
> A String in Elixir is a UTF-8 encoded binary.<br>
><br>
> However, Elixir is only able to show docs for Elixir modules. LFE is<br>
> only able to show docs for LFE functions and so on. If documentation<br>
> is standardized, such features can be easily added to other languages<br>
> in a way that works consistently across all BEAM languages.<br>
><br>
> Furthermore, each language ends up building their own tools for<br>
> generating, processing and converting documentation. We hope a unified<br>
> approach to documentation will improve the compatibility between tools.<br>
> For instance, an Erlang IDE will be able to show inline documentation<br>
> for any module and function, regardless if the function is part of OTP,<br>
> a library or even written in Elixir, LFE or Alpaca.<br>
><br>
> **Note**: in this document, the word “documentation” refers exclusively<br>
> to the API documentation of modules and functions. Guides, tutorials<br>
> and others materials are also essential to projects but not the focus<br>
> of this EEP.<br>
><br>
> **Note**: This EEP is not about documentation format. It is about a<br>
> mechanism for storing documentation to make it easier to produce other<br>
> formats. For example, a tool can read the documentation and produce man<br>
> pages from it.<br>
><br>
><br>
><br>
> Specification<br>
> =============<br>
><br>
> This EEP is divided in three parts. The first defines the two<br>
> places the documentation can be stored, the second defines the shape of<br>
> the documentation and the third discusses integration with OTP.<br>
><br>
><br>
> ## Part 1: the "Docs"storage ##<br>
><br>
> There are two main mechanisms in which BEAM languages store documentation:<br>
> in the filesystem (usually in the /doc directory) and inside ".beam"<br>
> files.<br>
><br>
> This EEP recognizes both options and aim to support both. To look for<br>
> documentation for a module name "example", a tool should:<br>
><br>
> 1. Look for "example.beam" in the code path, parse the BEAM file and<br>
> retrieve the "Docs" chunk<br>
><br>
> 2. If the chunk is not available, it should look for "example.beam"<br>
> in the code path and find the "doc/chunks/example.chunk" file in<br>
> the application that defines the "example" module<br>
><br>
> 3. If a ".chunk" file is not available, then documentation is not<br>
> available<br>
><br>
> The choice of using a chunk or the filesystem is completely up to the<br>
> language or library. In both cases, the documentation can be added or<br>
> removed at any moment by stripping the "Docs" chunk or by removing the<br>
> "doc/chunks" directory.<br>
><br>
> For example, languages like Elixir and LFE attach the "Docs" chunk at<br>
> compilation time, which can be controlled via a compiler flag. On the<br>
> other hand, projects like OTP itself will likely generate the "doc/chunks"<br>
> entries on a separate command, completely unrelated from code compilation.<br>
><br>
><br>
> ## Part 2: the "Docs" format ##<br>
><br>
><br>
> In both storages, the documentation is written in the exactly same<br>
> format: an Erlang term serialized to binary via term_to_binary/1. The<br>
> term may be optionally compressed when serialized and must follow the<br>
> type specification below:<br>
><br>
> {docs_v1,<br>
> Anno :: erl_anno:anno(),<br>
> Language :: atom(),<br>
> Format :: mime_type(),<br>
> ModuleDoc :: binary() | none | hidden,<br>
> Metadata :: map(),<br>
> Docs ::<br>
> [{{Kind, Name, Arity},<br>
> Anno :: erl_anno:anno(),<br>
> Signature :: [binary()],<br>
> Doc :: binary() | none | hidden,<br>
> Metadata :: map()<br>
> }]}<br>
><br>
> where in the root tuple we have:<br>
><br>
> * `Anno` - annotation (line, column, file) of the module documentation<br>
> or of the definition itself (see erl_anno)<br>
><br>
> * `Language` - an atom representing the language, for example:<br>
> "erlang", "elixir", "lfe", "alpaca", etc<br>
><br>
> * `Format` - the mime type of the documentation, such as "text/markdown"<br>
> (see the FAQ for a discussion on this field)<br>
><br>
> * `ModuleDoc` - a binary with the documentation or the atom "none"<br>
> in case there is no documentation or the atom "hidden" if<br>
> documentation has been explicitly disabled for this entry<br>
><br>
> * `Metadata` - a map of atom keys with any term as value. This can be<br>
> used to add annotations like the "authors" of a module, "deprecated",<br>
> or anything else a language or documentation tool may find relevant<br>
><br>
> * `Docs` - a list of documentation for other entities (such as<br>
> functions and types) in the module<br>
><br>
> For each entry in `Docs`, we have:<br>
><br>
> * `{Kind, Name, Arity}` - the kind, name and arity identifying the<br>
> function, callback, type, etc. The official entities are: `function`,<br>
> `type` and `callback`. Other languages will add their own. For<br>
> instance, Elixir and LFE may add `macro`<br>
><br>
> * `Anno` - annotation (line, column, file) of the module documentation<br>
> or of the definition itself (see erl_anno)<br>
><br>
> * `Signature` - the signature of the entity. It is is a list of<br>
> binaries. Each entry represents a binary in the signature that can<br>
> be joined with a whitespace or a newline. For example,<br>
> `["binary_to_atom(Binary, Encoding)", "when is_binary(Binary)"]`<br>
> may be rendered as as a single line or two lines. It exists<br>
> exclusively for exhibition purposes<br>
><br>
> * `Doc` - a binary with the documentation or the atom "none"<br>
> in case there is no documentation or the atom "hidden" if<br>
> documentation has been explicitly disabled for this entry<br>
><br>
> * `Metadata` - a map of atom keys with any term as value<br>
><br>
> This shared format is the heart of the EEP as it is what effectively<br>
> allows cross-language collaboration.<br>
><br>
> The `Metadata` field exists to allow languages, tools and libraries to<br>
> add custom information to each entry. This EEP documents the<br>
> following metadata keys:<br>
><br>
> * `authors := [binary()]` - a list of authors as binaries<br>
><br>
> * `cross_references := [module() | {module(), {Kind, Name, Arity}}]` -<br>
> a list of modules or module entries that can be used as cross<br>
> references when generating documentation<br>
><br>
> * `deprecated := binary()` - when present, it means the current entry<br>
> is deprecated with a binary that represents the reason for<br>
> deprecation and a recommendation to replace the deprecated code<br>
><br>
> * `since := binary()` - a binary representing the version such entry<br>
> was added, such as "1.3.0" or "20.0"<br>
><br>
> Any key may be added to Metadata at any time. Keys that are frequently<br>
> used by the community can be standardized in future versions.<br>
><br>
><br>
> ## Part 3: Integration with OTP ##<br>
><br>
> The last part focuses on integrating the previous parts with OTP docs,<br>
> tools and workflows. The items below are suggestions and are not<br>
> necessary for the adoption of this EEP, neither by OTP nor by any other<br>
> language or library.<br>
><br>
> At this point we should consider changes to OTP such as:<br>
><br>
> * Distributing the `doc/chunks/*.chunk` files as part of OTP and<br>
> changing the tools that ship with OTP to rely on them. For example,<br>
> "erl -man lists" could be changed to locate the "lists.chunk" file,<br>
> parsing the documentation out and then converting it to a man page<br>
> on the fly. This task may require multiple changes, as OTP stores<br>
> documentation on XML files as well as directly in the source code.<br>
> `edoc` itself should likely be augmented with functions that spit<br>
> out `.chunk` files from the source code<br>
><br>
> * Adding `h(Module)`, `h(Module, Function, Arity)`, and similar to<br>
> Erlang’s shell to print the documentation of a module or of a<br>
> given function and arity. This should be able to print docs any<br>
> other library or language that implements this proposal<br>
><br>
><br>
><br>
> FAQ<br>
> ===<br>
><br>
> *Q: Why do we have a Format entry in the documentation?*<br>
><br>
> The main trade-off in the proposal is the documentation format. We have<br>
> two options:<br>
><br>
> * Allow each language/library/tool to choose their own documentation<br>
> format<br>
> * Impose a unified documentation format on all languages<br>
><br>
> A unified format for documentation gives no flexibility to languages and<br>
> libraries in choosing how documentation is written. As the ecosystem<br>
> gets more diverse, it will be unlikely to find a format that suits all.<br>
> For this reason we introduced a Format field that allows each language<br>
> and library to pick their documentation format. The downside is that,<br>
> if the Elixir docs are written in Markdown and a language does not know<br>
> how to format Markdown, then the language will have to choose to either<br>
> not show the Elixir docs or show them raw (i.e. in Markdown).<br>
><br>
> Erlang is in a privileged position. All languages will be able to<br>
> support whatever format is chosen for Erlang since all languages run on<br>
> Erlang and will have direct access to Erlang's tooling.<br>
><br>
> *Q: If I have an Erlang/Elixir/LFE/Alpaca library that uses a custom<br>
> documentation toolkit, will I also be able to leverage this?*<br>
><br>
> As long as the documentation ends up up in the "Docs" chunk or inside<br>
> the `doc/chunks` directory, we absolutely do not care how the<br>
> documentation was originally written. If you use a custom format,<br>
> you may need to teach your language of choice how to render it though.<br>
> See the previous question.<br>
><br>
><br>
><br>
> Copyright<br>
> =========<br>
><br>
> This document has been placed in the public domain.<br>
><br>
><br>
><br>
> [EmacsVar]: <> "Local Variables:"<br>
> [EmacsVar]: <> "mode: indented-text"<br>
> [EmacsVar]: <> "indent-tabs-mode: nil"<br>
> [EmacsVar]: <> "sentence-end-double-space: t"<br>
> [EmacsVar]: <> "fill-column: 70"<br>
> [EmacsVar]: <> "coding: utf-8"<br>
> [EmacsVar]: <> "End:"<br>
> [VimVar]: <> " vim: set fileencoding=utf-8 expandtab shiftwidth=4 softtabstop=4: "<br>
> ______________________________<wbr>_________________<br>
> eeps mailing list<br>
> <a href="mailto:eeps@erlang.org">eeps@erlang.org</a><br>
> <a href="http://erlang.org/mailman/listinfo/eeps" rel="noreferrer" target="_blank">http://erlang.org/mailman/<wbr>listinfo/eeps</a><br>
<span class="HOEnZb"><font color="#888888"><br>
<br>
--<br>
<br>
/ Raimo Niskanen, Erlang/OTP, Ericsson AB<br>
______________________________<wbr>_________________<br>
eeps mailing list<br>
<a href="mailto:eeps@erlang.org">eeps@erlang.org</a><br>
<a href="http://erlang.org/mailman/listinfo/eeps" rel="noreferrer" target="_blank">http://erlang.org/mailman/<wbr>listinfo/eeps</a><br>
</font></span></blockquote></div><br></div>