[erlang-questions] edoc questions

[Fredrik Thulin]

Richard Carlsson wrote:
> Fredrik Thulin wrote:
>> Can you please be more specific? At the linked page, I found functions 
>> with edoc specifications like this one :
>>
>>    %@spec
>>    % go_b() -> {ok, Response}
>>
>> However, none of them seems to include a textual explanation of Response.
> 
> Currently, the way to do this is to put a sentence in the @doc part,
> e.g.:
> 
>   %% @doc ... `Dst' is the destination for this client transaction. ...
> 
> I have been considering adding separate tags for giving individual
> parameter descriptions, but alas, I have not had any time to implement
> it. Note, btw., that the `...' syntax will expand to <code>...</code>.

Ok, that is a show stopper for me but I'll definitely look at 
transforming YXAs documentation to edoc again in the future. I spent 
most of today writing a perl script to transform all my function 
documentations to edoc and this is a short list of other things I found 
problematic :

   * things like gen_server's init([Foo, Bar]) were not parsed. init(L)
     followed by L = [Foo, Bar], Foo = atom(), Bar = integer() did not
     parse either. Tuples like {Key, Value} did though.

   * functions that you provide more than one way of invoking (with more
     or less data provided by the user), for example

        do_stuff(In) ->
          Timeout = 5000,
          do_stuff(In, Timeout).
        do_stuff(In, Timeout) ->
          ...

     did not seem to be possible to document without a lot of redundant
     information.

   * saying that something has a return value including a timeout. In the
     gen_servers I have where I return timeouts from handle_call etc. I
     always define ?TIMEOUT at the top of the module, and return the
     defined value (for concistency) from the various function clauses.
       @spec(...) -> {reply, ok, State, ?TIMEOUT}
     didn't work.

   * saying that the result of one function is the result of some other,
     like a gen_server's start_link function having this in my current
     format "Returns : term(), result of gen_server:start_link/4". I
     guess this is actually the same feature request as the one you've
     already answered though.

/Fredrik