<html>
<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<p>-José—Eric—Radek—</p>
<p><br>
</p>
<p>This is fantastic news...especially with Code Beam coming up
shortly.<br>
</p>
<p>Attached is a typeset single-page printout of the root tuple
& description. <br>
</p>
<p>I find those easier to meditate on. <br>
</p>
<p>It's attached.</p>
<p><br>
</p>
<p>Cheers,</p>
<br>
Robert C. <br>
<br>
<br>
<br>
<br>
<div class="moz-cite-prefix">On 1/10/18 11:36 AM, José Valim wrote:<br>
</div>
<blockquote
cite="mid:CAGnRm4JqNWeM8n4ajSzBZ8MyyXm0JJL2+3tvcpMRNut6TW-yJg@mail.gmail.com"
type="cite">
<div dir="ltr">Thank you Raimo! I have sent a PR based on the
discussion in this mailing list: <a moz-do-not-send="true"
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
moz-do-not-send="true"
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 moz-do-not-send="true"
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 moz-do-not-send="true"
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 moz-do-not-send="true"
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 moz-do-not-send="true"
href="http://Valimwww.plataformatec.com.br"
rel="noreferrer" target="_blank">Valimwww.plataformatec.com.br</a><br>
> <<a moz-do-not-send="true"
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 moz-do-not-send="true"
href="mailto:eeps@erlang.org">eeps@erlang.org</a><br>
> <a moz-do-not-send="true"
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 moz-do-not-send="true" href="mailto:eeps@erlang.org">eeps@erlang.org</a><br>
<a moz-do-not-send="true"
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>
<br>
<fieldset class="mimeAttachmentHeader"></fieldset>
<br>
<pre wrap="">_______________________________________________
eeps mailing list
<a class="moz-txt-link-abbreviated" href="mailto:eeps@erlang.org">eeps@erlang.org</a>
<a class="moz-txt-link-freetext" href="http://erlang.org/mailman/listinfo/eeps">http://erlang.org/mailman/listinfo/eeps</a>
</pre>
</blockquote>
<br>
</body>
</html>