Bring add_doc/6 back, closes #7335

Author: José Valim

lib/elixir/lib/module.ex

@@ -1195,6 +1195,19 @@ defmodule Module do
     raise ArgumentError, "expected an Elixir module, got: #{inspect(original)}"
   end
 
+  @doc false
+  # TODO: Remove in 2.0 - deprecated.
+  def add_doc(module, line, kind, function_tuple, signature \\ [], doc) do
+    assert_not_compiled!(:add_doc, module)
+
+    if kind in [:defp, :defmacrop, :typep] do
+      if doc, do: {:error, :private_doc}, else: :ok
+    else
+      compile_doc(data_table_for(module), line, kind, function_tuple, signature, doc, __ENV__)
+      :ok
+    end
+  end
+
   @doc false
   # Used internally to compile documentation.
   # This function is private and must be used only internally.
@@ -1205,22 +1218,17 @@ defmodule Module do
     pair = {name, arity}
 
     impl = compile_impl(table, name, env, kind, args)
-    compile_doc(table, pair, env, kind, args, impl)
-    compile_deprecated(table, pair)
+    _deprecated = compile_deprecated(table, pair)
+    _since = compile_since(table)
 
-    :ok
-  end
-
-  defp compile_doc(table, pair, env, kind, args, impl) do
+    # TODO: Store @since and @deprecated alongside the docs
     {line, doc} = get_doc_info(table, env, impl)
+    compile_doc(table, line, kind, pair, args, doc, env)
 
-    # TODO: Store @since alongside the docs
-    _ = get_since_info(table)
-
-    add_doc(table, line, kind, pair, args, doc, env)
+    :ok
   end
 
-  defp add_doc(_table, line, kind, {name, arity}, _args, doc, env)
+  defp compile_doc(_table, line, kind, {name, arity}, _args, doc, env)
        when kind in [:defp, :defmacrop] do
     if doc do
       error_message =
@@ -1231,7 +1239,7 @@ defmodule Module do
     end
   end
 
-  defp add_doc(table, line, kind, pair, args, doc, env) do
+  defp compile_doc(table, line, kind, pair, args, doc, env) do
     signature = build_signature(args, env)
 
     case :ets.lookup(table, {:doc, pair}) do
@@ -1245,9 +1253,21 @@ defmodule Module do
     end
   end
 
+  defp compile_since(table) do
+    case :ets.take(table, :since) do
+      [{:since, since, _, _}] when is_binary(since) -> since
+      _ -> nil
+    end
+  end
+
   defp compile_deprecated(table, pair) do
-    if reason = get_deprecated_info(table) do
-      :ets.insert(table, {{:deprecated, pair}, reason})
+    case :ets.take(table, :deprecated) do
+      [{:deprecated, reason, _, _}] when is_binary(reason) ->
+        :ets.insert(table, {{:deprecated, pair}, reason})
+        reason
+
+      _ ->
+        nil
     end
   end
 
@@ -1736,17 +1756,6 @@ defmodule Module do
     end
   end
 
-  defp get_since_info(table) do
-    :ets.take(table, :since)
-  end
-
-  defp get_deprecated_info(table) do
-    case :ets.take(table, :deprecated) do
-      [{:deprecated, reason, _, _}] -> reason
-      [] -> nil
-    end
-  end
-
   defp data_table_for(module) do
     :elixir_module.data_table(module)
   end

lib/elixir/pages/Compatibility and Deprecations.md

@@ -35,6 +35,7 @@ Deprecated feature                               | Deprecated in | Replaced by (
 `Enum.partition/2`                               | [v1.6]        | `Enum.split_with/2` (v1.4)
 `Keyword.replace/3`                              | [v1.6]        | Use `Keyword.fetch/2` + `Keyword.put/3` (v1.0)
 `Macro.unescape_tokens/1` and `Macro.unescape_tokens/2` | [v1.6] | Use `Enum.map/2` to traverse over the arguments (v1.0)
+`Module.add_doc/6`                               | [v1.6]        | Use `@doc` instead
 `Map.replace/3`                                  | [v1.6]        | Use `Map.fetch/2` + `Map.put/3` (v1.0)
 `Range.range?/1`                                 | [v1.6]        | Pattern match on `_.._` instead (v1.0)
 `Atom.to_char_list/1`                            | [v1.5]        | `Atom.to_charlist/1` (v1.3)

lib/elixir/src/elixir_dispatch.erl

@@ -397,6 +397,10 @@ deprecation('Elixir.Macro', unescape_tokens, 1) ->
   "instead traverse over the arguments using Enum.map/2";
 deprecation('Elixir.Macro', unescape_tokens, 2) ->
   "instead traverse over the arguments using Enum.map/2";
+deprecation('Elixir.Module', add_doc, 5) ->
+  "use @doc instead";
+deprecation('Elixir.Module', add_doc, 6) ->
+  "use @doc instead";
 deprecation('Elixir.Range', 'range?', 1) ->
   "instead pattern match on left..right";
 deprecation('Elixir.Stream', filter_map, 3) ->

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

@@ -178,6 +178,9 @@ defmodule Kernel.DocsTest do
 
           @doc false
           def qux(true), do: false
+
+          Module.add_doc(__MODULE__, __ENV__.line, :def, {:nullary, 0}, [], "add_doc")
+          def nullary, do: 0
         end
       )
 
@@ -191,6 +194,7 @@ defmodule Kernel.DocsTest do
                {{:bar, 1}, _, :def, [{:arg, _, nil}], "Multiple bodiless clause doc"},
                {{:baz, 1}, _, :def, [{:arg, _, nil}], "Multiple bodiless clause and docs"},
                {{:foo, 1}, _, :def, [{:arg, _, nil}], "Function doc"},
+               {{:nullary, 0}, _, :def, [], "add_doc"},
                {{:qux, 1}, _, :def, [{:bool, _, Elixir}], false}
              ] = docs[:docs]