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

[Samuel Rivas]

Richard Carlsson wrote:
> Samuel Rivas wrote:
> >%% @type foo = record()
> >-record(foo, {
> >          bar, % @fieldType bar = integer()
> >          baz  % @fieldType baz = bool()
> >        }).
> I'm not too happy either about having to duplicate field names both in 
> the record declaration and in the edoc description, but allowing edoc to 
> use the form you suggested (and I have certainly thought about it 
> before, believe me) would require it to run the "epp_dodger" module in a 
> more exact mode in order to match the comments with the corresponding 
> fields (making it a bit slower, and more importantly: a lot more likely 
> to barf on weird uses of macros). Using a proper language extension like 
> that prototyped by the HiPE guys is much better, when/if it becomes 
> available, so I'm not going to implement the same thing with comments. 
> Meanwhile, you will have to live with some duplication.

I see.  Until improved type definitions are available, would it be worth
checking that the field names in the documentation are in the record 
definition? 

For example, edoc already checks other things like function arity:

%% @spec foo(bar, baz) -> []
foo(_) ->
  [].

Edoc will complain about bad arity in the specification.  I do not know
whether it is to expensive to do the same thing for records, knowing that
they may change in a future.

Regards.
-- 
	Samuel