ERL-1473: types mentioned in @type is not generated by edoc

[OTP-Maintainer]

Original reporter: slepher
Affected versions: OTP-23, OTP-24.0
Component: edoc
Migrated from: https://bugs.erlang.org/browse/ERL-1473

---

I was wring docs of a new feature which is going to contribute to syntax_tools.
and found it fails smoke-test in travis-ci.
it is caused by 

{quote}
Missing Anchor: "/lib/syntax_tools-2.4/doc/html/erl_syntax_traverse.html#type-traverse_style" from /lib/syntax_tools-2.4/doc/html/erl_syntax_traverse.html
{quote}

I found that tag of type traverse_style() 
{code:erlang}
-type traverse_style() :: traverse_step() | all | list.
-type traverse_step() :: pre | post | leaf.
{code}
is missing at doc/xml/erl_syntax_traverse.xml
{quote}
<tag><marker id="type-traverse_step"/>traverse_step() = pre | post | leaf</tag>
{quote}

so i write some sample code
{code:erlang}
-module(test_edoc).
-export_type([a/0]).
-type a() :: b().
-type b() :: hello.
{code}
and run 
rebar3 edoc
which generates
{quote}
<h3 class="typedecl"><a name="type-a">a()</a></h3>
<p><tt>a() = <a href="#type-b">b()</a></tt></p>
<h3 class="typedecl"><a name="type-b">b()</a></h3>
<p><tt>b() = hello</tt></p>
{quote}

when i add @type doc for a().
{code:erlang}
-module(test_edoc).
-export_type([a/0]).
%% @type a() = b().
%% 
%% hello world
%% 
-type a() :: b().
-type b() :: hello.
{code}
and run
rebar3 edoc
which generates 
{quote}
<h3 class="typedecl"><a name="type-a">a()</a></h3>
<p><tt>a() = <a href="#type-b">b()</a></tt></p>
<p>hello world
 </p>
<hr>
{quote}
and
{quote}
<h3 class="typedecl"><a name="type-b">b()</a></h3>
<p><tt>b() = hello</tt></p>
{quote}
disappeared

[OTP-Maintainer]

lukas said:

The conversion of edoc to erl_docgen xml only works for the scenarios that it needs to work for in order to generate the current documentation. So I'm not surprised that it is broken. I usually take a look at the documentation in syntax_tools in order to see how to write the documentation the way I want it.

We may get around to fixing this eventually for this type of links, but I do not think it will be anytime soon.

[paulo-ferraz-oliveira]

I can't seem to replicate this.

I still get (OTP 25 master)

<h3 class="typedecl"><a name="type-a">a()</a></h3>
<p><tt>a() = <a href="#type-b">b()</a></tt></p>
<h3 class="typedecl"><a name="type-b">b()</a></h3>
<p><tt>b() = hello</tt></p>

(with the second code example, containing @type) which seems to be what's expected.

On the other hand, though, I also get

.../src/test_edoc.erl, in module footer: at line 3: warning: EDoc @type tags are deprecated. Please use -type attributes instead.

which indicates this'll soon not be a problem anymore.