Callback attribute for better definition of behaviour callbacks.

[Stavros Aronis]

Hi!

On March the following thread appeared in the erlang-questions list:

http://www.erlang.org/cgi-bin/ezmlm-cgi?4:sss:50104:201003:hbmaknhcnnhjngliogof

In that thread there was discussion about how the current idiom to define a
behaviour lacks specific information about what the callbacks are supposed
to do. The proposal was to somehow use '-spec' attributes in order to
provide better information about the type of the arguments that each
callback function requires and its result. This patch implements this using
a new attribute: '-callback'.

The reason why the already existent '-spec' keyword can't be used is that
lint checks are performed to ensure that specs exist only for functions
defined in the module where the spec is defined. This is not what a callback
function requires, as it's going to be defined in another module.

These '-callback' attributes can then be used to automatically generate the
usual 'behaviour_info(callbacks)' export, required by the compiler to
confirm that a module that implements a behaviour exports all the required
callbacks.

The patch can be obtained with:

  git fetch git://github.com/aronisstav/otp.git callback-attr

Included in this patch are:

- updates in the syntax of Erlang (erl_parse.yrl) to allow the new attribute
with a form similar to that of the already familiar '-specs'
- updates in the lint (erl_lint) to ensure that no duplicates are defined
and no behaviour_info/1 function is defined as it will be automatically
generated and exported
- updates in the stdlib's, kernel's and inet's behaviours to use the new
syntax. The type information I've added is based on current published
documentation and comments in the files so it might be incorrect
and should be double-checked by someone who has more experience in the
actual usage of these behaviours than me.
- updates to the bootstrap files

Future additions:

- Dialyzer can use such attributes to find errors in the inferred callback
function types. (I've already implemented this but it's a different thing so
I'm gonna make a separate request for it)
- Documentation tools can use these attributes instead of comments to
specify the types of the arguments and the result of callback functions.

As this is my first patch, any feedback is gratefully accepted!

Stavros Aronis