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

Hynek Vychodil vychodil.hynek@REDACTED
Mon Oct 29 11:52:41 CET 2007


On 10/29/07, Richard Carlsson <richardc@REDACTED> wrote:
> 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
>
>

I have varying input parameters but coupling types between positions
and same result type. It's a little different, but you are right, it
can be good argument to rework interface too. It isn't so important
that if result type depend of input type. It is case when second
parameter meaning (not type) depends on first parameter type (and
meaning also). You right that redesign should make more clean
interface.

--Hynek (Pichi) Vychodil



More information about the erlang-questions mailing list