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

[Daniel Goertzen]

I am trying to document a "-type" close to the top of my modules like this...

%% @doc This type is awesome. Really, it is great.
-type key() :: binary() | atom().

... but it collides with my module @doc entry above it ("multiple @doc
tag" error).

Is there a right way to document types or is this not supported right
now? The generated documentation shows all my types nicely, but I'd
love to have a bit of explanation appear with them.

Thanks,
Dan.
_______________________________________________
erlang-questions mailing list
erlang-q...@erlang.org
http://erlang.org/mailman/listinfo/erlang-questions

[Richard Carlsson]

On 2011-07-12 23:25, Daniel Goertzen wrote:
> I am trying to document a "-type" close to the top of my modules like this...
>
> %% @doc This type is awesome. Really, it is great.
> -type key() :: binary() | atom().
>
> ... but it collides with my module @doc entry above it ("multiple @doc
> tag" error).
>
> Is there a right way to document types or is this not supported right
> now? The generated documentation shows all my types nicely, but I'd
> love to have a bit of explanation appear with them.

It's not supported right now, but it's a good idea. Thanks.

/Richard

[Lukas Larsson]

Hi,

It is not supported via the traditional edoc syntax, however it is supported by the new type documentation generation. If you write

-type key() :: binary() | atom().
%% This type is awesome.  Really, it is great.

The comment below the type will be included in the generated edoc.

Lukas

[Serge Aleynikov]

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>

> On Wednesday, July 13, 2011 1:30:43 PM UTC+4, Lukas Larsson wrote:
> Hi,
>
> It is not supported via the traditional edoc syntax, however it
> is supported by the new type documentation generation. If you write
>
> -type key() :: binary() | atom().
> %% This type is awesome. Really, it is great.
>
> The comment below the type will be included in the generated edoc.
>
> Lukas

[Hans Bolinder]

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

[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
>

[Hans Bolinder]

Hi,

My mistake. Sorry. The answer was meant to be sent to Nico Kruber.

I'll send it again, in the correct thread.

BR

[Magnus Henoch]

Serge Aleynikov <se...@aleynikov.org> writes:

> 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?

I played with your example a bit, and found that the documentation does
get included if the closing square bracket is on the same line as the
second alternative:

-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.

Tested with edoc from R15B03. Hope this helps someone find the bug...

Regards,
Magnus

[Serge Aleynikov]

Thanks for the workaround. Does sound like a bug in edoc.

[Hans Bolinder]

Hi,

There is a patch at https://github.com/uabboli/otp/commit/f4db123786408d23c1497fbc4a875d47f304c64d.

It will hopefully make it into the upcoming R16B release.

Best regards,

Hans Bolinder, Erlang/OTP, Ericsson AB