[erlang-questions] edoc questions

[Fredrik Thulin]

Hi

I'm looking at turning the documentation of ~1900 existing function 
documentations into edoc. I have a number of questions already, and 
there will surely be follow-ups with more questions from me. As an 
introduction, I'll show you an example of my current documentation 
syntax, and begin with a warming up question ;).

All documented functions in YXA have comments like this (hi Håkan) :

%%--------------------------------------------------------------------
%% Function: start_client_transaction(Request, Dst)
%%           Request = request record()
%%           Dst     = sipdst record(), the destination for this
%%                     client transaction
%% Descrip.: Start a new client transaction.
%% Returns : Pid        |
%%           {error, E}
%%           Pid = pid()
%%           E   = string()
%%--------------------------------------------------------------------

My first question is :

    How can I preserve the explanatory text for Dst?

And also, I understand that documenting records using edoc isn't exactly 
finished yet (?). I use lots of records, often defined in included .hrl 
files. I would like to see two things here,

   a) I could define a type, request(), that is basically a request
      record. I think it would be nice if the edoc documentation for a
      record could look like <link>#request{}</link> for such, instead of
      <link>request()</link> - forcing the reader to jump around between
      different parts of the HTML page - possibly loosing concentration.

   b) The type declaration of my #request{} record would have to go into
      the same .hrl file - everything else would be utterly impractical.
      Modules not actually making use of a record should not be bloated
      with the unused records declaration in the "data types" section
      though.

/Fredrik