[erlang-questions] edoc: documenting "-type"

[Serge Aleynikov]

Hans,

The example I posted below didn't include any hrl files (if that is what
you are referring to), and my question was why the comments immediately
following the type proto() were parsed correctly, and the comments
following the type options() didn't get processed by edoc.

I don't think the limitation you are talking about explains that oddity.

Serge

On 2/18/2013 8:11 AM, Hans Bolinder wrote:
> Hi Serge,
> 
> If I'm not mistaken, it's a known limitation of EDoc. See edoc(3), read_source/2, the preprocess option:
> 
>   Note: comments in included files will not be available to EDoc, even
>   with this option enabled.
> 
> Best regards,
> 
> Hans Bolinder, Erlang/OTP, Ericsson AB
> 

On 2/1/2013 10:20 AM, Serge Aleynikov wrote:
> I have a similar question. In the following test module the generated
> documentation for proto() type includes proper comment, but the
> options() doc doesn't include comment.  It seems to be immaterial if "%%
> Protocol options." appear on the same line as the ending "]." of the
> options() type or the next line. Why is the edoc generator doesn't
> include comment for the options() type?
>
> -module(test).
> -export([t/2]).
>
> -type proto() :: tcp | ssl.
> %% Protocol type.
>
> -type options() :: [
>           {server, Server::string()}
>         | {port, Port::integer()}
>         ].
> %% Protocol options.
> %%     * Server - server to connect to (no MX lookup)
> %%     * Relay  - domain to do MX lookup of list of servers
>
> -spec t(Proto :: proto(), Options :: options()) -> ok.
> t(_Proto, _Options) -> ok.
>
>
> Segment of relevant generated docs:
>
> <h3 class="typedecl"><a name="type-options">options()</a></h3>
> <p><pre>options() =
>     [{server, Server :: string()} | {port, Port :: integer()}]</pre></p>
>
> <h3 class="typedecl"><a name="type-proto">proto()</a></h3>
> <p><pre>proto() = tcp | ssl</pre></p>
> <p>  Protocol type.</p>