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

[Kostis Sagonas]

Richard Carlsson wrote:
> Samuel Rivas wrote:
> 
>>Hello,
>>
>>  Is there any simple way to document a public .hrl file with record
>>definitions.  I would like to document the record definitions in the hrl
>>file, but I do not know how to make edoc parse it, nor how to document a
>>record (apart from the ad-hoc solution of document the in the XHTML part
>>of type definitions and link those types from the overview.edoc file).
>>
>>  Regards.
> 
> 
> It hasn't been documented yet, but look in the lib/edoc/src/edoc.hrl 
> file for an example, 

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:

------------------------------------------
%% @type tag() = #tag{name = atom(),
%%                    line = integer(),
%%                    data = term()}

-record(tag, {name, line = 0, data}).
------------------------------------------

is possible to be written as simply as:

-------------------------------------------------------------
-record(tag, {name :: atom(), line = 0 :: integer(), data}).
-------------------------------------------------------------

I must stress that this feature is currently UNDOCUMENTED, EXPERIMENTAL
(i.e., bound to change or even disappear) and totally UNSUPPORTED.

We do have plans to make this a reality and integrate it with the rest
of OTP (e.g. use types which are compatible or recognizable by edoc).
But this will have to wait for a future OTP release -- perhaps R12.

However, since at least one user asked for this ability, we invite the
community for comments and wishes.

Best,
Kostis