Today, EEP has an Anno field for each entry, which is documented as follows:

Anno - annotation (line, column, file) of the module documentation or of the definition itself (see erl_anno)

The issue, however, is that Erlang has distinct locations for documentation and source code. In order to not introduce a breaking change to EEP 48, I propose:

1. Enforce Anno to be about the source code
2. Introduce an edit_url metadata field that contains the URL for editing the documentation

Currently, EEP 48 supports a signature field, which is a list of binaries. The signature is pre-rendered. This means tools rendering the documentation only has to concern themselves with printing each line individually.

However, this definition of the signature is not enough for IDEs, which would most likely need to know each argument name and their type, as well as the return type, individually. We should discuss if adding this information is within the scope of EEP 48 and how to effectively add it.

For example, one immediate complication of showing args and return types, is that typespecs in Erlang/Elixir may have multiple clauses, which means there is not a value to show per argument, but multiple of them. Both edoc and Elixir support this style, but not Erlang/OTP XML (afaik).

Hi everyone,

We were asked to make a report on the WG recent efforts. Part of it will also be a video to be presented at CodeBEAM. I think we should touch four topics:

1. Erlang/OTP 23 supports EEP 48 and discuss the new helpers in the terminal (thanks to the Ericsson team)
2. Edoc is being worked on by Radek to also follow EEP 48 (show a link where people can try it out)
3. Elixir master supports reading/showing Erlang docs in the terminal
4. ExDoc is being improved to generate docs for Erlang projects too, v0.22 already has some improvements in this direction

Anything else?

This is a thread to track the progress and any pending tasks that may arise during this effort.

The current idea is that Erlang/OTP XML will be converted to an HTML tree data-structure. This is better than storing HTML as text as we don't have to parse it again.

The tree will have the following format:

Ast :: [Node]
Node :: binary() | {Tag, Attributes, Ast} | {Tag, Ast}
Tag :: binary()
Attributes :: [{binary(), binary()}]

Note: We may remove {Tag, Ast} as it can be represented as {Tag, [], Ast}. The question is if the size will increase considerably or not by doing so.

Note: Currently, EEP 48 requires documentation to be stored as binaries. This means that the HTML tree would have to be converted as term_to_binary and then the whole chunk is converted to term_to_binary again. This is most likely OK, converting a binary with term_to_binary is a fast operation with minimum space increase, but worth noting. The mime type should be something "application/erlang-abstract-format+html".

You can track the current progress here.

TODO

• Merge multipe for the same arity.
• Have a look at specs and types to see if we can do something better with them
• Check what has/can be done to ease lsp integration.
• Skip wild HTML elements when rendering
• Fix all links to work properly. This will include changes to the source xml as right now we cannot see any difference between a link to a User's Guide and to a Reference Manual.
• Remove nested <p>
• Make all attributes binaries
• Add pagianation for h/1 and friends, see c:i/0 for details
• Add link type checker
• Move <section> in the refman xml to only be allowed inside <description>
• Add callbacks to the chunks
• Fix duplicate function documentation when doing h(ttb,tpl)
• Add deprecation attributes to the meta-data for functions
• Fix , and . alone on new-line when after a tagged string.
• Document the application/erlang+html format and the EEP-48 format.
• Expand the shell_docs:validate/1 function to follow a stricter dtd.
• Add proper tests for shell_docs:render/* by using the dtd.

Don't do

• Forbid multiple <funcs> tags in the source xml
• Wrap all <li> contents with a <p> (don't think I will do this as it will change the meaning of things)

Now that the doc comments become really first class citizens in the BEAM ecosystem. It would be nice if the compiler could warn about missing edocs on exported functions, not unlike -compile(warn_missing_spec).
It is certainly possible to achieve the same result with a separate tool, but since warn_missing_spec is implemented in the compiler, it makes sense to follow suite if only for consistency.

I realize that this is very Erlang-centric description, but I am not familiar with other ecosystem languages enough to suggest a more generic problem statement.

This thread documents the progress on generating ExDoc documentation for Erlang projects.

Current status

erszcz/edoc@0c81cea can be used to generate chunks compatible with erlang/otp@dd3b015 as follows:

git clone https://github.com/ferd/recon
cd recon
cat >> rebar.config <<END

{plugins,
 [
  {rebar3_edoc_chunks, {git, "https://github.com/erszcz/edoc.git", {branch, "master"}}}
 ]}.

{provider_hooks,
 [
  {post, [{compile, {edoc_chunks, compile}}]}
 ]}.
END
rebar3 compile
ls _build/default/lib/recon/doc/chunks/

ToDo

• Aim for 100% compatibility with application/erlang+html format.
• Define a set of HTML tags which are allowed in the chunks (likely starting with tags from https://developer.mozilla.org/en-US/docs/Web/HTML/Element but removing those which are obviously not useful in an .erl file / non-dynamic webpage).
• Make sure EDoc documentation discourages use of raw HTML in doc comments.
• Make sure that links to modules/functions/types/callbacks are stored properly.
• Include since and deprecated information in the chunks:
  • @since
  • @deprecated - partially supported, see erszcz/edoc@ed5f585. EDoc @deprecated might contain markup, but EEP-48 expects a flat binary() for this metadata field - currently, all markup is dropped in the chunks.
• Remove temporary edoc_layout_chunk_markdown layout and refactor the rest for simplicity:
  • Remove edoc_layout_chunk_markdown.
  • Refactor.
• Prepare a PR to erlang/otp - this will likely squash the forked project history.
• Once the PR is created, If need be also fix NEW-OPTIONS: / INHERIT-OPTIONS: doc comments - I'm not sure how to use these yet, though.
• From 2020-03-10 WG meeting: have a command line tool to generate the chunks.
  The escript doesn't yet handle -I, i.e. adding custom include paths, but it hasn't yet occurred to be a problem.

2020-04-01 update:

• tt, expr, see, strong tag handling - these pop up in Recon and EDoc itself
• ex_doc consuming doc chunks could not generate EDoc documentation due to the types exported to chunk and types exported to Dbgi not matching. This is solved by rewriting all @spec / @type tags to -spec/-type attributes (currently only for edoc.erl)
• HTML generated by ex_doc for edoc.erl (after spec/type rewrite) has some documentation entries truncated, e.g. for the deprecated file/2