Add soft deprecation attributes to modules

Author: José Valim

lib/elixir/lib/behaviour.ex

@@ -1,15 +1,19 @@
 defmodule Behaviour do
   @moduledoc """
-  WARNING: this module is deprecated.
+  Mechanism for handling behaviours.
 
-  Instead of `defcallback/1` and `defmacrocallback/1`, the `@callback` and
-  `@macrocallback` module attributes can be used (respectively). See the
-  documentation for `Module` for more information on these attributes.
+  This module is deprecated. Instead of `defcallback/1` and
+  `defmacrocallback/1`, the `@callback` and `@macrocallback`
+  module attributes can be used (respectively). See the
+  documentation for `Module` for more information on these
+  attributes.
 
   Instead of `MyModule.__behaviour__(:callbacks)`,
   `MyModule.behaviour_info(:callbacks)` can be used.
   """
 
+  @moduledoc deprecated: "Use @callback and @macrocallback attributes instead"
+
   @doc """
   Defines a function callback according to the given type specification.
   """

lib/elixir/lib/dict.ex

@@ -1,6 +1,6 @@
 defmodule Dict do
   @moduledoc ~S"""
-  WARNING: this module is deprecated.
+  Generic API for dictionaries.
 
   If you need a general dictionary, use the `Map` module.
   If you need to manipulate keyword lists, use `Keyword`.
@@ -9,6 +9,8 @@ defmodule Dict do
   `new` function in the respective modules.
   """
 
+  @moduledoc deprecated: "Use Map or Keyword modules instead"
+
   @type key :: any
   @type value :: any
   @type t :: list | map

lib/elixir/lib/gen_event.ex

@@ -4,7 +4,7 @@ defmodule GenEvent do
   # Functions from this module are deprecated in elixir_dispatch.
 
   @moduledoc """
-  WARNING: this module is deprecated.
+  A event manager with event handlers behaviour.
 
   If you are interested in implementing an event manager, please read the
   "Alternatives" section below. If you have to implement an event handler to
@@ -43,6 +43,8 @@ defmodule GenEvent do
   [`:gen_event`](http://erlang.org/doc/man/gen_event.html) Erlang module.
   """
 
+  @moduledoc deprecated: "Use Erlang/OTP's :gen_event module instead"
+
   @callback init(args :: term) ::
               {:ok, state}
               | {:ok, state, :hibernate}

lib/elixir/lib/hash_dict.ex

@@ -1,10 +1,12 @@
 defmodule HashDict do
   @moduledoc """
-  WARNING: this module is deprecated.
+  Tuple-based HashDict implementation.
 
-  Use the `Map` module instead.
+  This module is deprecated. Use the `Map` module instead.
   """
 
+  @moduledoc deprecated: "Use Map instead"
+
   # TODO: Remove by 2.0
 
   use Dict

lib/elixir/lib/hash_set.ex

@@ -1,11 +1,11 @@
 defmodule HashSet do
   @moduledoc """
-  WARNING: this module is deprecated.
+  Tuple-based HashSet implementation.
 
-  Use the `MapSet` module instead.
+  This module is deprecated. Use the `MapSet` module instead.
   """
 
-  # TODO: Remove by 2.0
+  @moduledoc deprecated: "Use MapSet instead"
 
   @node_bitmap 0b111
   @node_shift 3

lib/elixir/lib/set.ex

@@ -1,10 +1,12 @@
 defmodule Set do
   @moduledoc ~S"""
-  WARNING: this module is deprecated.
+  Generic API for sets.
 
-  Use the `MapSet` module instead.
+  This module is deprecated, use the `MapSet` module instead.
   """
 
+  @moduledoc deprecated: "Use MapSet instead"
+
   @type value :: any
   @type values :: [value]
   @type t :: map

lib/elixir/lib/supervisor/spec.ex

@@ -1,6 +1,6 @@
 defmodule Supervisor.Spec do
   @moduledoc """
-  WARNING: this module is deprecated.
+  Outdated functions for building child specifications.
 
   The functions in this module are deprecated and they do not work
   with the module-based child specs introduced in Elixir v1.5.
@@ -106,6 +106,9 @@ defmodule Supervisor.Spec do
 
   """
 
+  @moduledoc deprecated:
+               "Use the new child specifications outlined in the Supervisor module instead"
+
   # TODO: Deprecate all functions in this module on Elixir v1.8.
   # Also deprecate entry in Supervisor.Default.