[erlang-questions] Accessing the documentation at runtime

[Vlad Dumitrescu]

On Wed, Sep 28, 2016 at 9:44 PM, Joe Armstrong <erlang@REDACTED> wrote:

> Regarding an API
>
> It is not a coincidence that the HTML documentation for (say
> lists.erl) can be obtained by fetching the page
> http://erlang.org/doc/man/lists.html
>
> How about a REST interface to extract the parts of the documentation?
>
> For example
>
>  http://erlang.org/doc/man/lists?type=xml
>  would fetch the lists.xml (the documentation)
>
>  http://erlang.org/doc/man/lists?type=erl
> (the code)
>
>  and
> http://erlang.org/doc/man/lists?type=xml&func=append&arity=2
> would fetch the documentation for lists:append/2 etc.
>

>From other comments on the documentation thread, there are many people that
work offline, so accessing the documentation via internet is not useful.
Even so, I would like to cache it locally, so it could be saved in an
archive just as we said before.

If we *standardise* the interface then writing tools to present this in
> different ways should possible
>

We can standardise it just as well as to accessing the local file, how it
gets there is another issue. Maybe it was downloaded, maybe it was
installed, maybe it was built.

BTW, we also want to make sure that we use the documentation matching the
current version of the module, so we need the module's version attribute as
key.

regards,
Vlad


>
> On Wed, Sep 28, 2016 at 8:28 PM, Vlad Dumitrescu <vladdu55@REDACTED>
> wrote:
> > Hi,
> >
> > Following the documentation discussion, and the details about how Elixir
> > supports that as API, I wonder if we could (should?) support something
> > similar for Erlang.
> >
> > My suggestion for the data to store is the xml source, parsed with xmerl
> > into simple-form. For non-otp modules, there is an edoclet that can
> produce
> > opt-like xml from edoc. I don't know what format elixir uses, but for
> > consuming the OTP docs this feels the easiest.
> >
> > One way is to add an optional chunk to the beam files, storing the docs.
> A
> > new compiler option would select that, similar to 'debug'. This would
> > increase the size of the files significantly and possibly only few people
> > will add the docs, resulting in an useless chunk, but if it gets used
> then
> > all data is readily available.
> >
> > An alternative would be to deliver archives with the docs in separate
> files
> > (a zip in myapp/doc?).
> >
> > What is needed then is an API to access that, "code:get_doc(Module|App)"
> > feels like it would be enough.
> >
> > Thoughts?
> >
> > best regards,
> > Vlad
> >
> >
> > _______________________________________________
> > erlang-questions mailing list
> > erlang-questions@REDACTED
> > http://erlang.org/mailman/listinfo/erlang-questions
> >
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20160928/da065186/attachment.htm>