Erlang support

[wojtekmach]

• [x] Basic support
• [x] Render typespecs using erl_pp/erl_prettypr
• [x] Highlight erlang code examples
• [x] Autolink Erlang typespecs
• [x] Rewrite links. E.g. {:a, [rel: "https://erlang.org/doc/link/seemfa", href: "stdlib:array#new/0", ...} is rewritten to, based on what docs we generate, an internal link to array.html#new/0 or external one to erlang.org.
• [x] Warn on invalid refs
• [x] Make sure source_url is correct (e.g. https://hexdocs.pm/hex_core/hex_registry.html#t:private_key/0 isn't.)
• [x] Support docs.config
• [ ] Support admonition blocks
• [ ] (UI) Search by module:fun/arity
• [x] (UI) Footer link: [Erlang programming language](https://erlang.org)

TODOs:

• [x] don't crash building diameter docs (https://github.com/erlang/otp/pull/5160)
• [ ] incorrect specs: https://wojtekmach.pl/otp_docs/erts/erlang.html#fun_info/2, https://wojtekmach.pl/otp_docs/erts/erlang.html#monitor/2. We're not handling xml <type> tags correctly: https://github.com/erlang/otp/blob/f59eac7b9ce50df08ba583edf5b4d66b7a3b7c7a/erts/doc/src/erlang.xml#L4065:L4068
• [ ] No newline between multiple clauses in a signature: https://wojtekmach.pl/otp_docs/stdlib/gen_statem.html#c:StateName/3
• [ ] no syntax highlighting for some code block: https://wojtekmach.pl/otp_docs/erts/erlang.html#is_map_key/2
• [ ] no support for <seeguide>, <seefile>, <seefile>, etc. https://wojtekmach.pl/otp_docs/kernel/application.html#module-see-also. Not sure how to best handle those, I guess we'd create an extras page for each of them?
• [ ] incorrect link [`Memory Allocation`](#content#system_info_allocator) in https://wojtekmach.pl/otp_docs/erts/erlang.html#system_info/1
• [ ] incorrectly displaying inline code: (https://wojtekmach.pl/otp_docs/erts/erlang.html#summary)
• [ ] duplicate entries for the same fun/arity in the sidebar: (https://wojtekmach.pl/otp_docs/erts/erlang.html) this is because we have multiple chunk entries but we should still see if we can handle it better, even if just collapsing to a single link in the sidebar

[felipedotcom]

Hello, It is possible to tackle one of those?

[josevalim]

Definitely! :) You can start for example with the first one availables, such as "(UI) Search by module:fun/arity" and "(UI) Footer link: Erlang programming language". :)

[felipedotcom]

sorry for the trouble but I'm not sure how to start tho, I've cloned the ex_doc repo, but I failed to see where should I start the implementation. I'll need a little help plz

[the-mikedavis]

Support for Erlang Extras would also be useful.

Currently there's a TODO for not hard-coding as Elixir: https://github.com/elixir-lang/ex_doc/blob/6ad3fdd375a91f2e9bc9c566b8cae1cbb9d1001b/lib/ex_doc/formatter/html.ex#L387-L388

If the language is not passed through, auto-link doesn't work for functions written with Erlang syntax, like here in the Telemetry README Extra.

You can instead use the Elixir syntax (":telemetry.execute/3"), but then the generated link uses that same syntax which looks out-of-place in documentation that uses Erlang syntax otherwise.

I would be interested in working on this but I wonder which syntax Erlang auto-links should use? Should they be written in an ExDoc-like syntax with t::module.type/0 or use EDoc reference syntax?

[josevalim]

PRs welcome! Let’s use ExDoc syntax but using Erlang notation. :)

[the-mikedavis]

There's a small bug with types that take parameters:

-type ok(T) :: {ok, T}.
%% ...
%% {@link ok()}

EDoc provides #ok/0 for the {@link ok()} reference which will fail to autolink and causes a warning. (Example)

I'm not sure how to solve this in ExDoc - it happens for remote types too so you would need to look up all types for the local or remote module with the same name and find the one with the highest arity. Maybe this should be solved in EDoc instead?

[maennchen]

When working with an application, which is managed by mix and contains both Elixir (lib) and Erlang (src), the Erlang modules are not added to the documentation.

I tracked this down to a difference in how Elixir & Erlang are handling the documentation chunks. Elixir contains the chunks directly in the compiled .beam module, Erlang does not. Instead edoc can generate those chunks into a separate file.

To overcome this, I have created a mix alias for mix docs, which calls edoc first:

https://github.com/erlef/oidcc/blob/648f0cf451b2269b6dda3da61ae86b1e8b97668b/mix.exs

defmodule Oidcc.Mixfile do

  # ...

  def project() do
    [
      # ...
      aliases: [docs: ["compile", &edoc_chunks/1, "docs"]],
      # ...
    ]
  end

  # ...

  defp edoc_chunks(_args) do
    base_path = Path.dirname(__ENV__.file)
    doc_chunk_path = Application.app_dir(:oidcc, "doc")

    :ok =
      :edoc.application(:oidcc, String.to_charlist(base_path),
        doclet: :edoc_doclet_chunks,
        layout: :edoc_layout_chunks,
        preprocess: true,
        dir: String.to_charlist(doc_chunk_path)
      )
  end
end

This feels a bit like a hack and I'm wondering if it would make sense, to either call edoc in Mix.Tasks.Docs or possibly even in Mix.Tasks.Compile.Erlang to ensure that the docs chunks are present.

[wojtekmach]

or possibly even in Mix.Tasks.Compile.Erlang to ensure that the docs chunks are present.

@maennchen ideally this would happen in erlc or more realistically in rebar3 compile. If that happens not only Elixir but importantly also Erlang projects will get access to docs. E.g.:

$ cd /project/that/uses/recon
$ rebar3 shell
> h(recon).

so yeah, it's best if someone pursues this on the Erlang tooling side.

[maennchen]

@wojtekmach Since Mix.Tasks.Compile.Erlang doesn't use rebar, we would have to do the changes both in mix and rebar3, correct? (Given we don't want to push for erlc at the moment.)

If yes, I'll go ahead and open issues for both.

[wojtekmach]

Oh, right, you meant erl files managed by Mix. I believe edoc is slowly going away so to be future proof a separate package that helps might be a better starting point anyway.

[josevalim]

@wojtekmach @garazdawi once you have some time, please let us know which one of these are still relevant (and should be tackled) and which ones are fixed or no longer matters. :) I will be nice to finally close this. :)

[garazdawi]

For application/html+erlang there are still a lot of things left to be done. However for Erlang with markdown I think most/all of the above are done.

Since we will be trying to migrate/coax the Erlang community to use Markdown for docs I think that we can ignore application/html+erlang for now which means that we can close this issue.

The only potentially thing I see remaining is "incorrectly displaying inline code:". Which is more related to the fact that it is impossible in markdown to create links within code blocks, so you have to resort to schenanigans like this:

[`lists:sum`](`lists:sum/1`)`(`[`lists:seq`](`lists:seq/2`)`(1,100)`

to get links into code examples and since ExDoc puts a border around inline code segments the above does not look very nice.

[josevalim]

Perfect.