[eeps] EEP XXX: Documentation storage and format

[Vlad Dumitrescu]

Hi!

This would be a very useful thing to implement, IMHO.

The chunks could also be located in a zip archive, or online, so maybe a
{uri, URI} value is more general than a {path, Path} one? For example, the
docs for OTP would be much easier to distribute as an archive that doesn't
need to be unpacked than one that has to be unpacked at the right place and
create hundreds of small files. Similarily, if the docs are not available
locally, they could be retrieved from a URL and cached locally.

Actually, why restrict this to handling the documentation? If the
information about the module is moved as an item in Docs (at the cost of
non-uniform key structure), then the top-level is generic and can be used
to store all kinds of metadata about code entities (making Docs a map where
'docs' is just one of the keys). I have an use-case (cross-reference
information), and maybe even dialyzer could store plt data in this
distributed manner (not sure if it would work or help, just guessing).

On the other hand, these different kind of data would better be kept
separate, it's not really needed to use a single chunk. But the basic tools
to create and use these chunks can very well be common, I think.

best regards,
Vlad


On Thu, Jan 4, 2018 at 10:59 PM, José Valim <jose.valim@REDACTED> wrote:

> This EEP proposes an official API documentation storage to be used by
> by BEAM languages.  By standardizing how API documentation is stored,
> it will be possible to write tools that work across languages.
>
> I want to thank Eric and Radek, who co-authored the proposal, as well as
> Kenneth, Fred, Tristan and Loïc for their feedback.
>
> See the attached document.
>
> *José Valimwww.plataformatec.com.br
> <http://www.plataformatec.com.br/>Founder and Director of R&D*
>
> _______________________________________________
> eeps mailing list
> eeps@REDACTED
> http://erlang.org/mailman/listinfo/eeps
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/eeps/attachments/20180106/f6b163c1/attachment.htm>