[erlang-questions] edoc questions

[Michael McDaniel]

  first question, please see below ...

On Mon, Dec 04, 2006 at 12:32:19PM +0100, Fredrik Thulin wrote:
> 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) :

%% @doc
%% @author Fredrik
%%<pre>
%%--------------------------------------------------------------------
%% 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()
%%--------------------------------------------------------------------
%%</pre>
%% @end

 a brief (incomplete) example is at http://autosys.us/misc/vipin.erl

~Michael


> 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
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://www.erlang.org/mailman/listinfo/erlang-questions
> 
> !DSPAM:52,4574078674993735421272!
> 
> 

-- 
Michael McDaniel
Portland, Oregon, USA
http://autosys.us
+1 503 283 5284