[erlang-questions] Providing documentation via API

Vlad Dumitrescu vladdu55@REDACTED
Mon Oct 3 22:31:33 CEST 2016


Hi,

If we are to be able to provide an API to locate and extract documentation
for code constructs, what would be a good format to return it in? The
source can be code comments or external files, which means that there will
be multiple possible source formats (edoc, xml, asciidoc, rst, markdown,
etc).

I can see the following alternatives:
* raw: textual data as in the source, the clients have to parse and
interpret it
* display: textual data that can be rendered (basically, HTML)
* structured: some data structure that unifies the different sources; some
kind of plug-ins providing parser support are needed.

The 'raw' solution will be needed by the other two to retrieve the doc
sources, but are the others useful to have in the library? I would like to
be able to provide the 'structured' format.

This is the kind of API I am looking at:
https://gist.github.com/vladdu/aa571a548cecfeb85b84c65378429bf0 (thanks Joe
for pointing me in this direction!). There should also be a way to
configure the location of the external docs.

best regards,
Vlad
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20161003/a7c6f63c/attachment.htm>


More information about the erlang-questions mailing list