[erlang-questions] Documenting records and .hrls with edoc

[Samuel Rivas]

Kostis Sagonas wrote:
> It has also not been documented anywhere, but for the needs of the
> Dialyzer and TypEr tools, we have experimentally modified the parser in
> the upcoming Erlang/OTP R11B-2 release to accept type declarations in
> records.
> 
> So, Richard's example from the above file that currently looks as:
> [snipped] 
> is possible to be written as simply as:
> 
> -------------------------------------------------------------
> -record(tag, {name :: atom(), line = 0 :: integer(), data}).
> -------------------------------------------------------------
> [snipped]
> However, since at least one user asked for this ability, we invite the
> community for comments and wishes.

I think it is a good idea to inline type documentation in the record
declarations. This avoid mistyping when you duplicate field names.
However, I was wondering on something like doxygen's /**< */ blocks to
keep current comment syntax. A quick example:

%% @type foo = record()
-record(foo, {
          bar, % @fieldType bar = integer()
          baz  % @fieldType baz = bool()
        }).

Undoubtedly, previous notation can be improved with more careful
thinking.

I had not thought of unifying type definitions for dyalizer, typer and
edoc, but is seems a great idea.

  Regards
-- 
	Samuel