[erlang-questions] Providing documentation via API

[Vlad Dumitrescu]

On Mon, Oct 3, 2016 at 11:10 PM, Richard Carlsson <
carlsson.richard@REDACTED> wrote:

> There is of course already https://github.com/erlang/otp/
> blob/maint/lib/edoc/priv/edoc.dtd, but it might need updating.
>

Yes, and that's a very good base for the structured documentation data. I
think the OTP docs structure is a subset of this format.

I don't want to care where exactly and in which format the documentation
is.

best regards,
Vlad



>         /Richard
>
> 2016-10-03 22:31 GMT+02:00 Vlad Dumitrescu <vladdu55@REDACTED>:
>
>> 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/vl
>> addu/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
>>
>>
>> _______________________________________________
>> 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/20161004/c3455c71/attachment.htm>