search

aws-beam / aws-codegen

Code generator for AWS clients in Erlang and Elixir.
Other
53 stars 49 forks source link

Improve generated Erlang documentation #58

Closed philss closed 3 years ago

philss commented 3 years ago

This PR makes the generated EDoc documentation (Erlang) more easier to read and more concise, according to rules from the Wiki notation.

Demo

:point_right: https://tmp-aws-docs-erlang-dxsraxvsv.vercel.app/ The generated code is in the following PR: https://github.com/aws-beam/aws-erlang/pull/37

philss commented 3 years ago

An observation is that I couldn't generate docs for all the modules. Some of the HTML is breaking Edoc for about 4 modules, and I don't think it worth to fix them all. I will investigate more later today.

jfacorro commented 3 years ago

An observation is that I couldn't generate docs for all the modules. Some of the HTML is breaking Edoc for about 4 modules, and I don't think it worth to fix them all. I will investigate more later today.

I've found this before as well. There are some documentation strings that have broken HTML tags, where there is an opening but no closing tag. I guess the library/code used to convert HTML to markdown in the generation of documentation for the Elixir client is handling this kind of unexpected input?

philss commented 3 years ago

I've found this before as well. There are some documentation strings that have broken HTML tags, where there is an opening but no closing tag. I guess the library/code used to convert HTML to markdown in the generation of documentation for the Elixir client is handling this kind of unexpected input?

It is ignoring the problems and rendering a broken HTML for those modules. It is not good, but at least it is possible to read something. I will try to solve some of problems, but I'm not sure if in this PR or a new one. But I will let you know.

philss commented 3 years ago

@jfacorro I couldn't fix all the issues today :/ There are 3 remaining. I will merge this PR and open an issue to tackle that another time. :)

jfacorro commented 3 years ago

@jfacorro I couldn't fix all the issues today :/ There are 3 remaining. I will merge this PR and open an issue to tackle that another time. :)

That sounds awesome. Thank you!