Introduce @deprecated module attribute

[josevalim]

The plan is to use it alongside xref and print compile time warnings to deprecated functions. Docs can use it in the future too.

[ggcampinho]

I want to try this one!

[josevalim]

@ggcampinho please go ahead! Some notes:

1. During compilation we can store it as we store documentation using a {{deprecated, {name, arity}}, deprecation_reason} entry or similar (I can't quite recall how we store docs).

2. We need to validate the reason is a string (similar to how we validate @since)

3. When emitting the Erlang bytecode, we will add an extra chunk called "ExDp" that will return {{name, arity}, reason}. We will also store it under __info__(:deprecated).

4. We will change xref to invoke __info__(:deprecated) or read from the chunk and emit the proper warnings.

We can probably do this over multiple PRs. One PR could do 1 to 3, another could do 4.

[whatyouhide]

@josevalim did we decide we want to store the deprecation reason in the chunk? I still think storing the version it was deprecated in in the chunk and just mentioning the reason in the documentation might be a better idea. However I wonder if this would mean that we would not do @doc false anymore on deprecated functions.

[josevalim]

@whatyouhide I think storing the reason is better because that is more immediately useful for developers for warnings coming from xref.

Compare:

foo.ex:3: String.contain?/2 was deprecated. Use String.contains?/2 instead.

with:

foo.ex:3: String.contain?/2 was deprecated (on version v1.3.2)

And I would say the version it was deprecated is not very important. The version the replacement was introduced and the version it will be removed (if one is scheduled) are more important.

[whatyouhide]

@josevalim okay, fair enough. 👍

[michalmuskala]

One thing to consider is that both this attribute and @since might be problematic for libraries that want to be compatible with multiple elixir versions because of the unused attribute warnings. I'm not sure what would be the best course of action here.

[whatyouhide]

@michalmuskala they can have a _ = @since to be compatible without warnings?