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

[Richard Carlsson]

Samuel Rivas wrote:
> 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'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.

     /Richard