[erlang-questions] beginer: How to specify multifunction in edoc

[Richard Carlsson]

Hynek Vychodil wrote:
> No, it isn't what I really want. I want something like this:
> 
> http://erlang.org/doc/man/ets.html#update_counter/6
> 
> But where all parameters changes and only some parameters types works together.
> 
> open(File::file_handler(), Procs::integer()) -> {ok, handler()}
> open(FileName::list(), BlkSize::integer()) -> {ok, handler()}
> 
> But open(File::file_handler(), BlkSize::integer()) and
> open(FileName::list(), Procs::integer()) are nonsense. I want write it
> in @spec tag and I wouldn't like use open(FilenameOrHandler,
> ProcsOrBlkSize) because only two from four combinations have mater.

EDoc doesn't support this style of documentation, and that is a design
decision. The OTP docs are (at least traditionally) written in a more
or less free-form style, and nobody really expects to be able to read
them automatically and use those specifications for things like type
analysis - they are often a bit too "loose" and require a human to
interpret their meaning.

The example you point to, update_counter/6, could easily be described
using normal edoc syntax, since it actually returns the same type
regardless of the exact type of its parameters:

  @spec update_counter(Tab, Key, How) -> Result
    where
         How = {Pos,Incr,Threshold,SetValue} | {Pos,Incr} | Incr,
         ...
         Result = integer()

In almost all cases when you feel the need to use this kind of
documentation, where the output type depends on the input type:
   foo(integer()) -> integer();
   foo(atom()) -> atom().

it means that you are doing the wrong thing, and that you should
probably redesign your interface. (Trust me on this one.)

     /Richard