[erlang-questions] edoc questions

Håkan Stenholm hokan.stenholm@REDACTED
Mon Dec 4 21:07:10 CET 2006

Fredrik Thulin wrote:

>Richard Carlsson wrote:
>>Fredrik Thulin wrote:
>>>  * 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.
>>Can you give a full example of what you mean with "things like
>>gen_server's init([Foo, Bar]) were not parsed"? Who did not parse
>>what, exactly?
> >
>>For the rest, you should remove the commas between the type 
>>declarations. Just write
>>    X1 = type1
>>        ...
>>    Xn = typeN
>Sorry for not being clear. For example, this is the startup part of a 
>typical gen_server of mine :
>start_link(Request, Dst, Branch, Timeout, ReportTo) ->
>     gen_server:start(?MODULE, [Request, Dst, Branch, Timeout, ReportTo,
>		     self()], []).
>%% @spec    ([Request, Dst, Branch, Timeout, ReportTo, Parent]) ->
>%%            {ok, State}          |
>%%            {ok, State, Timeout} |
>%%            ignore               |
>%%            {stop, Reason}
>%%            Request  = #request{}
>%%            Dst      = #sipdst{}
>%%            Branch   = string()
>%%            Timeout  = integer()
>%%            ReportTo = pid() | none
>%%            Parent   = pid()
>%% @doc     Initiates a client transaction handler. Set us up for an
>%%          immediate timeout signal in which we will try to send out
>%%          our request - to not block caller.
>%% @end
>init([Request, Dst, Branch, Timeout, ReportTo, Parent]) ->
>    ...
>And this is the error message I get from edoc :
>./new_clienttransaction.erl, function init/1: at line 131: syntax error 
>before: ','
>edoc: skipping source file './new_clienttransaction.erl': {'EXIT',error}.
>edoc: error in doclet 'edoc_doclet': {'EXIT',error}.
>{"init terminating in do_boot",error}
>Line 131 is the @spec line. Using edoc from R11B-2.
>>You can look at the edoc source code for more usage examples.
>I have, and yikes - what is all that HTML making it so hard to read the 
>documentation in emacs? ;)
>>>  * 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.
>>The easiest is to use @equiv. Write the full documentation for 
>>do_stuff/2, and for do_stuff/1, specify @equiv do_stuff(In, 5000).
>>This covers 99% of typical uses of multiple arities; for special
>>cases, write some text that describes precisely what happens.
>Fair enough.
>>I decided to strictly separate functions with different arities in
>>edoc, because I had already seen too many cases of documentation
>>where people had written something like this:
>>   f(X)
>>   f(X, Y)
>>   f(X, Y, Z)
>>   f(W, X, Y, Z)
>>   where
>>       X = a | b | c
>>       Y = {foo, ...} | {bar, ...}
>>       Z = pid() | atom() | string()
>>       W = [binary()] | binary()
>>   Returns:
>>       Something | SomethingElse | OtherThings | VariousStuff
>>   Bla bla bla bla bla...
>>and then totally failed to describe precisely which combinations of
>>arguments were legal and which were not, and which return values (and
>>possible errors) would result from which argument combinations.
>>Documenting them as if they were a single function is the sort of
>>thing that looks like a good idea for small examples, but can get
>>completely out of hand very quickly. Separate documentation is a
>>small price to pay for the added clarity. (It also forces you to
>>think for a moment about what the different versions actually do.)
This is one of the things that actualy bothers me about edoc as I
occasionally end up with code like: 

get_x(....) ->
get_y(....) ->
get_z(....) ->

where it would be nice to a have common comment like:

%% ------------------------------------------------------
%% @spec  get_xx(....) -> ....
%% @doc   each get_xx/N retrieves the field xx from ...
%% @end--------------------------------------------------

instead of:

%% ------------------------------------------------------
%% get_xx(....) -> ....
%% each get_xx/N retrieves the field xx from ...
%% ------------------------------------------------------

which works as documentation but kind of breaks the html

Or as in your example, which could be clarified as:

%% ------------------------------------------------------
%% @spec f(X)          -> R    (default Y = ...)
%%       f(X, Y)       -> R    (default Z = ...)
%%       f(X, Y, Z)    -> R    (default W = ...)
%%       f(W, X, Y, Z) -> R   
%% ....

assuming a f/1 -> f/2 -> f/3 -> f/4 call sequence

>Not to say that you are wrong, but I do wonder what all those people who 
>thinks the compiler shouldn't output warnings for suspicious code 
>because they don't want a particular coding style enforced of them would 
>think about having a documentation style enforced on them ;). I wonder 
>what is worst. Maybe code style, because documentation is much more 
>optional than code =).
>>>  * 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.
>>Well, no surprise, since macro preprocessing is not done in comments.
>Sure, but since edoc happily accepts for example never explained 
>variables (like if it would have said just Timeout), it strikes me a bit 
>odd that it doesn't allow macros even if it doesn't know about them.
>>>  * 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.
>>Usually, that's the sort of implementation detail that you should not
>>put in the documentation, unless it's a simple equivalence (as in the
>>@equiv example above). When you really want to document this kind of
>>fact anyway, just write it in the @doc text.
>Sure, this would be no problem if I were starting a new project. 
>Converting 1900 pieces of documentation has to be done programmatically 
>though, and this is part of my legacy.
>erlang-questions mailing list

More information about the erlang-questions mailing list