Allow :deprecated to be given as doc metadata

Author: José Valim

lib/elixir/lib/kernel/typespec.ex

@@ -170,31 +170,9 @@ defmodule Kernel.Typespec do
   end
 
   defp get_doc_meta(spec_meta, doc_kind, set) do
-    doc_meta =
-      case :ets.take(set, {doc_kind, :meta}) do
-        [{{^doc_kind, :meta}, metadata, _}] -> Map.merge(metadata, spec_meta)
-        [] -> spec_meta
-      end
-
-    doc_meta
-    |> get_since_info(set)
-    |> get_deprecated_info(set)
-  end
-
-  defp get_since_info(doc_meta, set) do
-    case :ets.take(set, :since) do
-      [{:since, since, _}] when is_binary(since) -> Map.put_new(doc_meta, :since, since)
-      _ -> doc_meta
-    end
-  end
-
-  defp get_deprecated_info(doc_meta, set) do
-    case :ets.take(set, :deprecated) do
-      [{:deprecated, reason, _}] when is_binary(reason) ->
-        Map.put_new(doc_meta, :deprecated, reason)
-
-      _ ->
-        doc_meta
+    case :ets.take(set, {doc_kind, :meta}) do
+      [{{^doc_kind, :meta}, metadata, _}] -> Map.merge(metadata, spec_meta)
+      [] -> spec_meta
     end
   end
 

lib/elixir/lib/module.ex

@@ -125,11 +125,26 @@ defmodule Module do
   The Mix compiler automatically looks for calls to deprecated modules
   and emit warnings during compilation, computed via `mix xref warnings`.
 
-  The `@deprecated` attribute may also be used to annotate callbacks or
-  types. In these cases the annotation is only informational and doesn't
-  come with compile time checks. In any case, the annotation will also
-  become part of the documentation metadata to be used by tools like
-  ExDoc or IEx.
+  Using the `@deprecated` attribute will also be reflected in the
+  documentation of the given function and macro. You can choose between
+  the `@deprecated` attribute and the documentation metadata to provide
+  hard-deprecations (with warnings) and soft-deprecations (with warnings):
+
+  This is a soft-deprecation as it simply annotates the documentation
+  as deprecated:
+
+      @doc deprecated: "Use Kernel.length/1 instead"
+      def size(keyword)
+
+  This is a hard-deprecation as it emits warnings and annotates the
+  documentation as deprecated:
+
+      @deprecated "Use Kernel.length/1 instead"
+      def size(keyword)
+
+  Currently `@deprecated` only supports functions and macros. However
+  you can use the `:deprecated` key in the annotation metadata to
+  annotate the docs of modules, types and callbacks too.
 
   We recommend using this feature with care, especially library authors.
   Deprecating code always pushes the burden towards library users. We
@@ -181,7 +196,7 @@ defmodule Module do
 
   Note that since the compiler also defines some additional metadata,
   there are a few reserved keys that will be ignored and warned if used.
-  Currently these are: `:opaque`, `:defaults`, and `:deprecated`.
+  Currently these are: `:opaque` and `:defaults`.
 
   ### `@dialyzer`
 
@@ -1336,8 +1351,7 @@ defmodule Module do
   defp doc_key(:defmacro), do: :macro
 
   defp compile_doc_meta(set, bag, name, arity, defaults) do
-    doc_meta = compile_since(%{}, set)
-    doc_meta = compile_deprecated(doc_meta, set, bag, name, arity, defaults)
+    doc_meta = compile_deprecated(%{}, set, bag, name, arity, defaults)
     doc_meta = get_doc_meta(doc_meta, set)
     add_defaults_count(doc_meta, defaults)
   end
@@ -1349,13 +1363,6 @@ defmodule Module do
     end
   end
 
-  defp compile_since(doc_meta, table) do
-    case :ets.take(table, :since) do
-      [{:since, since, _}] when is_binary(since) -> Map.put(doc_meta, :since, since)
-      _ -> doc_meta
-    end
-  end
-
   defp compile_deprecated(doc_meta, set, bag, name, arity, defaults) do
     case :ets.take(set, :deprecated) do
       [{:deprecated, reason, _}] when is_binary(reason) ->
@@ -1764,7 +1771,7 @@ defmodule Module do
   # We do not insert into the :attributes key in the bag table
   # because those attributes are deleted on every definition.
   defp put_attribute(module, key, value, line, set, _bag)
-       when key in [:doc, :typedoc, :moduledoc, :impl, :since, :deprecated] do
+       when key in [:doc, :typedoc, :moduledoc, :impl, :deprecated] do
     try do
       :ets.lookup_element(set, key, 3)
     catch
@@ -1812,7 +1819,7 @@ defmodule Module do
       {line, doc} when is_integer(line) ->
         raise ArgumentError,
               "@#{key} is a built-in module attribute for documentation. It should be " <>
-                "a binary, boolean, keyword list, or nil, got: #{inspect(doc)}"
+                "a string, boolean, keyword list, or nil, got: #{inspect(doc)}"
 
       _other ->
         raise ArgumentError,
@@ -1878,13 +1885,6 @@ defmodule Module do
             "dependencies. It should be a string the path to a file, got: #{inspect(value)}"
   end
 
-  defp preprocess_attribute(:since, value) when not is_binary(value) do
-    raise ArgumentError,
-          "@since is a built-in module attribute used for documentation purposes. " <>
-            "It should be a string representing the version a function, macro, type or " <>
-            "callback was added, got: #{inspect(value)}"
-  end
-
   defp preprocess_attribute(:deprecated, value) when not is_binary(value) do
     raise ArgumentError,
           "@deprecated is a built-in module attribute that annotates a definition as deprecated. " <>
@@ -1902,7 +1902,7 @@ defmodule Module do
       _ ->
         raise ArgumentError,
               "@file is a built-in module attribute that annotates the file and line the next " <>
-                "definition comes from. It should be a string or a {string, line} tuple as value, " <>
+                "definition comes from. It should be a string or {string, line} tuple as value, " <>
                 "got: #{inspect(value)}"
     end
   end
@@ -1914,8 +1914,8 @@ defmodule Module do
   defp preprocess_doc_meta([], _module, _line, map), do: map
 
   defp preprocess_doc_meta([{key, _} | tail], module, line, map)
-       when key in [:opaque, :defaults, :deprecated] do
-    message = "ignoring reserved documentation metadata key: :#{key}"
+       when key in [:opaque, :defaults] do
+    message = "ignoring reserved documentation metadata key: #{inspect(key)}"
     IO.warn(message, attribute_stack(module, line))
     preprocess_doc_meta(tail, module, line, map)
   end
@@ -1927,9 +1927,14 @@ defmodule Module do
 
   defp validate_doc_meta(:since, value) when not is_binary(value) do
     raise ArgumentError,
-          ":since is a built-in documentation metadata key. " <>
-            "It should be a string representing the version a function, macro, type or " <>
-            "callback was added, got: #{inspect(value)}"
+          ":since is a built-in documentation metadata key. It should be a string representing " <>
+            "the version in which the documented entity was added, got: #{inspect(value)}"
+  end
+
+  defp validate_doc_meta(:deprecated, value) when not is_binary(value) do
+    raise ArgumentError,
+          ":deprecated is a built-in documentation metadata key. It should be a string " <>
+            "representing the replacement for the deprecated entity, got: #{inspect(value)}"
   end
 
   defp validate_doc_meta(_, _), do: :ok

lib/elixir/src/elixir_module.erl

@@ -33,7 +33,6 @@ is_open(Module) ->
 delete_definition_attributes(#{module := Module}, _, _, _, _, _) ->
   {DataSet, _} = data_tables(Module),
   ets:delete(DataSet, doc),
-  ets:delete(DataSet, since),
   ets:delete(DataSet, deprecated),
   ets:delete(DataSet, impl).
 
@@ -332,7 +331,7 @@ warn_unused_attributes(File, DataSet, DataBag, PersistedAttrs) ->
   StoredAttrs = bag_lookup_element(DataBag, attributes, 2),
   %% This is the same list as in Module.put_attribute
   %% without moduledoc which are never warned on.
-  Attrs = [doc, typedoc, impl, since, deprecated | StoredAttrs -- PersistedAttrs],
+  Attrs = [doc, typedoc, impl, deprecated | StoredAttrs -- PersistedAttrs],
   Query = [{{Attr, '_', '$1'}, [{is_integer, '$1'}], [[Attr, '$1']]} || Attr <- Attrs],
   [elixir_errors:form_warn([{line, Line}], File, ?MODULE, {unused_attribute, Key})
    || [Key, Line] <- ets:select(DataSet, Query)].
@@ -405,8 +404,8 @@ format_error({unused_attribute, impl}) ->
   "module attribute @impl was set but no definition follows it";
 format_error({unused_attribute, deprecated}) ->
   "module attribute @deprecated was set but no definition follows it";
-format_error({unused_attribute, since}) ->
-  "module attribute @since was set but no definition follows it";
+format_error({unused_attribute, since}) -> %% TODO: Remove this on v1.8
+  "module attribute @since is deprecated, please use \"@doc since: ...\" instead";
 format_error({unused_attribute, Attr}) ->
   io_lib:format("module attribute @~ts was set but never used", [Attr]);
 format_error({invalid_module, Module}) ->

lib/elixir/test/elixir/kernel/docs_test.exs

@@ -70,7 +70,7 @@ defmodule Kernel.DocsTest do
       end
     end
 
-    assert_raise ArgumentError, ~r/should be a binary, boolean, keyword list, or nil/, fn ->
+    assert_raise ArgumentError, ~r/should be a string, boolean, keyword list, or nil/, fn ->
       defmodule AtSyntaxDocAttributesFormat do
         @moduledoc :not_a_binary
       end
@@ -155,9 +155,8 @@ defmodule Kernel.DocsTest do
           @opaque bar(any) :: any
 
           @doc "Callback doc"
-          @doc since: "1.2.3", color: :red
+          @doc since: "1.2.3", color: :red, deprecated: "use baz/2 instead"
           @doc color: :blue, stable: true
-          @deprecated "use baz/2 instead"
           @callback foo(any) :: any
 
           @doc false
@@ -170,13 +169,12 @@ defmodule Kernel.DocsTest do
 
           @doc "Function doc"
           @doc since: "1.2.3", color: :red
-          @since "1.2-doc-meta-takes-precedence"
           @doc color: :blue, stable: true
           @deprecated "use baz/2 instead"
           def foo(arg \\ 0), do: arg + 1
 
           @doc "Multiple bodiless clause doc"
-          @since "1.2.3"
+          @deprecated "something else"
           def bar(_arg)
           def bar(_arg)
           def bar(arg), do: arg + 1
@@ -235,7 +233,7 @@ defmodule Kernel.DocsTest do
       assert {{:function, :__struct__, 1}, _, ["__struct__(kv)"], :none, %{}} = function_struct_1
 
       assert {{:function, :bar, 1}, _, ["bar(arg)"], %{"en" => "Multiple bodiless clause doc"},
-              %{since: "1.2.3"}} = function_bar
+              %{deprecated: "something else"}} = function_bar
 
       assert {{:function, :baz, 1}, _, ["baz(arg)"],
               %{"en" => "Multiple bodiless clause and docs"}, %{since: "1.2.3"}} = function_baz

lib/elixir/test/elixir/kernel/warning_test.exs

@@ -1142,7 +1142,7 @@ defmodule Kernel.WarningTest do
       capture_err(fn ->
         Code.eval_string("""
         defmodule Sample do
-          @typedoc opaque: false, deprecated: "do not use"
+          @typedoc opaque: false
           @type t :: binary
 
           @doc defaults: 3, since: "1.2.3"
@@ -1152,7 +1152,6 @@ defmodule Kernel.WarningTest do
       end)
 
     assert output =~ "ignoring reserved documentation metadata key: :opaque"
-    assert output =~ "ignoring reserved documentation metadata key: :deprecated"
     assert output =~ "ignoring reserved documentation metadata key: :defaults"
     refute output =~ ":since"
   after

lib/ex_unit/lib/ex_unit/doc_test.ex

@@ -189,18 +189,18 @@ defmodule ExUnit.DocTest do
   """
   defmacro doctest(module, opts \\ []) do
     require =
-      if is_atom(Macro.expand(mod, __CALLER__)) do
+      if is_atom(Macro.expand(module, __CALLER__)) do
         quote do
-          require unquote(mod)
+          require unquote(module)
         end
       end
 
     tests =
-      quote bind_quoted: [mod: mod, opts: opts] do
+      quote bind_quoted: [module: module, opts: opts] do
         env = __ENV__
-        file = ExUnit.DocTest.__file__(mod)
+        file = ExUnit.DocTest.__file__(module)
 
-        for {name, test} <- ExUnit.DocTest.__doctests__(mod, opts) do
+        for {name, test} <- ExUnit.DocTest.__doctests__(module, opts) do
           @file file
           doc = ExUnit.Case.register_test(env, :doctest, name, [])
           def unquote(doc)(_), do: unquote(test)