@behaviour, @callback and @spec

[Eiji]

@asummers

You don’t need them as Dialyzer will give a callback does not match spec error, but please include them anyway. As a reader I do not want to have to jump to the behaviour definition to find out what the arguments are. In that vein if you include a using macro where you define default callbacks that are overridable with defoverridable, elide the spec in the using macro, otherwise you’ll get a compiler error for duplicating the spec if anyone actually overrides.

I don’t like such ideas as it’s really a pain for maintainers of libraries in case multiple libraries are implementing specified behaviour. Imagine that one behaviour is used by 10 libraries and 3 of them are not updated - what to do in such case? Should someone fork it just to update @docs?

Personalyl I think that introducing macro for documentation is a bit too overcomplicated. In such cases I would prefer to use h helper in iex (or just html documentation) and docs delegating feature:

@doc delegate_to: {Foo, :bar, 3}

This would add a link which could be used in h helper (or just clicked on html page). In such case there is no need to change same documentation for multiple implementations or write any macros.