Partially fix abstract Erlang types ({@type ...})

[paulo-ferraz-oliveira]

@type is deprecated but still documented: you get a warning upon documentation generation.

This surfaced at jelly-beam/rebar3_ex_doc#38.

Code out in the wild may contain references like the ones we include in the test.

This pull request attempts at solving a basic case for those.

EDoc seems broken for some types of @type (or at least not generating useful information), but at least this commit prevents a crash.

While discussing the solution with @starbelly we didn't know where to put the normalisation code. It might be good here, or it might belong in the doc_ast.ex module.

[josevalim]

I wouldn’t try to do anything smart. Can we just leave the HTML as is, making sure it does not crash?

[paulo-ferraz-oliveira]

Wdym? Not putting code inside the a? Or the type- thing?

[paulo-ferraz-oliveira]

Or simply avoiding the crash but not taking {@type ...} into account either (since it's deprecated)?

[paulo-ferraz-oliveira]

I'll do a new commit to simply avoid the crash and nothing else.

[paulo-ferraz-oliveira]

This is what's visible with the updated code (01b6065)

Links are not usable, because generated HTML (in doc) points to e.g. #type-myList, while anchor is identified (above) as #t:myList/0.

[paulo-ferraz-oliveira]

Using all @type examples from EDoc we get

and no crashes 👍 (except in the tests - if I try to create some for the examples, but I'm not sure if you want me to "fix" that too)

Edit: specifically, crash is in

    {:docs_v1, _, _, "application/erlang+html", %{"en" => doc}, _, _} =
      Code.fetch_docs(:erlang_foo)

when matching (that %{"en" => doc} is empty). Looking closely at the AST, it seems this happens because types declared like that get "hoisted" up. (if this makes sense) - in EDoc's docs: "All data type descriptions are placed in a separate section of the documentation, regardless of where the tags occur."

[paulo-ferraz-oliveira]

I added this to the tests (locally - autolink_doc - where search and arity are new function arguments)

        {:docs_v1, _, _, "application/erlang+html", %{}, _, extra} ->
          [{_, _, _, %{"en" => doc}, _}] =
            Enum.filter(extra, fn
              {{:type, ^search, ^arity}, _, _, _, _} -> true
              _ -> false
            end)

as well as more tests, but maybe it's not worth it (?) I can push if you wanna.

[josevalim]

If @wojtekmach is happy, I am happy!

[wojtekmach]

Thank you! I'd strip out the <a> and just leave <code> but it definitely doesn't hurt to keep it this way for now.