[erlang-questions] edoc questions

[Richard Carlsson]

Fredrik Thulin wrote:
> %% @spec    ([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: ','
> [...]
> Line 131 is the @spec line.

The problem here is that [Request, ..., Parent] is not a valid type
specification. You can only specify that the parameter is a list of
some particular kind of elements (in any order), e.g. [integer()].
If the function had used a tuple instead of a list for passing the
arguments to init/1, there would be no problem. This is a matter of
expressiveness of the type system - but I know no language where the
type system lets you specify elements of a list that have different
types depending on their position. I suggest you either change the
function interface, if it's just an internal implementation detail.
Otherwise, you'll have to write something like this:

   %% @spec (Arguments::list()) -> ...
   %% @doc ... The `Arguments' list must have the form [Request,
   %% ..., Parent], where `Request' is a `#request{}' record, ...

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

Macros (i.e., names prefixed with `?', are simply not part of
the edoc type specification language. They only exist in the
preprocessor, and not in any other part of Erlang.

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

I suggest using less perl scripts and more emacs macros. I have
rewritten the docs for syntax_tools and other things multiple times
during the development of edoc, and emacs is a much greater help than
anything else.

     /Richard