[erlang-questions] edoc questions

[Håkan Stenholm]

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) :
>
>%%--------------------------------------------------------------------
>%% 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()
>%%--------------------------------------------------------------------
>

Using edoc I (hokan) would probably rewrite this as follows:

%%--------------------------------------------------------------------
%% @spec  start_client_transaction(Request::record(request), 
%%        Dst::record(sipdst)) -> Pid::pid() | {error, E::string()}
%% @doc   Start a new client transaction.
%%       
%%        Dst = the destination for this client transaction
%% @end---------------------------------------------------------------

* All type info is pushed up into the @spec part
* exceptions need to be put into @throw and '@error' - which doesn't exist,
  so runtime errors end up in @doc (possibly on a "%% error:   ...." line).
* extra type info / descriptions get pushed down into the @doc part - I
  kind of prefer to keep the variable comments after the initial comments,
  this is an advantage if the edoc is to be read as html files, where the
  initial @doc line/paragraph is used as a summary description.

If the documentation is to be read as html (something which I have no
particular need of[1] here at Kreditor), one may also resort to things like
``` ''' to quote blocks of comments, this is fairly unobtrusive in regard
to the readabilty of the comments - I rather dislike littering the source
code comments with html tags that makes the docs hard to read.

Blank edoc lines introduces a new html paragraph (<p> tag) which is 
sometimes
also handy e.g. @doc above expands into two paragraphs.


[1]: I use edoc mainly because we (Kreditor) nowdays use it as a reasonably
     standarized typenotation that may be useful in the future - even
     though some things are kind of akward to express in edoc.
     On the other hand as we (usualy) don't build libraries/APIs for 
external
     use, there is very little interest to ensure that the produced html
     makes any kind of sense. 

>
>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.
>
It would be nice if every record type in a @spec was a clickable link,
linking to a .hrl html file. This could be achived by edoc, by examining all
the include / include_lib .hrl entries used by a specific .erl files, so 
that
the correct record definition (e.g. if the is more than one foobar record
defined) can be associated with each created record link.

>
>   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
>
>