Show docs for callback with multiple clauses (#8553)

* Merge callback's multiple clauses in elixir_erl.erl
* Simpler callbacks deduplication

Author: wojtekmach

lib/elixir/lib/kernel/typespec.ex

@@ -108,8 +108,11 @@ defmodule Kernel.Typespec do
 
     case spec_to_signature(expr) do
       {name, arity} ->
-        {line, doc} = get_doc_info(set, :doc, line)
-        store_doc(set, kind, name, arity, line, :doc, doc, %{})
+        # store doc only once in case callback has multiple clauses
+        unless :ets.member(set, {kind, name, arity}) do
+          {line, doc} = get_doc_info(set, :doc, line)
+          store_doc(set, kind, name, arity, line, :doc, doc, %{})
+        end
 
       :error ->
         :error

lib/elixir/src/elixir_erl.erl

@@ -320,7 +320,12 @@ typespecs_form(Map, TranslatedTypespecs, MacroNames) ->
   Forms1 = types_form(Types, Forms0),
   Forms2 = callspecs_form(spec, Specs, [], MacroNames, Forms1, Map),
   Forms3 = callspecs_form(callback, AllCallbacks, OptionalCallbacks, MacroCallbackNames, Forms2, Map),
-  {Types, AllCallbacks, Forms3}.
+
+  AllCallbacksWithoutSpecs = lists:usort([
+    {Kind, Name, Arity} || {Kind, {Name, Arity}, _Line, _Spec} <- AllCallbacks
+  ]),
+
+  {Types, AllCallbacksWithoutSpecs, Forms3}.
 
 %% Types
 
@@ -518,8 +523,7 @@ get_callback_docs(Set, Callbacks) ->
     [],
     doc_value(Doc),
     Meta
-   } || {Kind, {Name, Arity}, _, _} <- Callbacks,
-        {Key, Line, Doc, Meta} <- ets:lookup(Set, {Kind, Name, Arity})].
+   } || Callback <- Callbacks, {Key, Line, Doc, Meta} <- ets:lookup(Set, Callback)].
 
 get_type_docs(Set, Types) ->
   [{Key,

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

@@ -164,9 +164,17 @@ defmodule Kernel.DocsTest do
           @callback bar() :: term
           @callback baz(any, term) :: any
 
+          @doc "Callback with multiple clauses"
+          @callback callback_multi(integer) :: integer
+          @callback callback_multi(atom) :: atom
+
           @doc "Macrocallback doc"
           @macrocallback qux(any) :: any
 
+          @doc "Macrocallback with multiple clauses"
+          @macrocallback macrocallback_multi(integer) :: integer
+          @macrocallback macrocallback_multi(atom) :: atom
+
           @doc "Function doc"
           @doc since: "1.2.3", color: :red
           @doc color: :blue, stable: true
@@ -210,6 +218,7 @@ defmodule Kernel.DocsTest do
       [
         callback_bar,
         callback_baz,
+        callback_multi,
         callback_foo,
         function_struct_0,
         function_struct_1,
@@ -219,6 +228,7 @@ defmodule Kernel.DocsTest do
         function_nullary,
         function_qux,
         guard_is_zero,
+        macrocallback_multi,
         macrocallback_qux,
         type_bar,
         type_foo
@@ -231,6 +241,9 @@ defmodule Kernel.DocsTest do
               %{since: "1.2.3", deprecated: "use baz/2 instead", color: :blue, stable: true}} =
                callback_foo
 
+      assert {{:callback, :callback_multi, 1}, _, [], %{"en" => "Callback with multiple clauses"},
+              %{}} = callback_multi
+
       assert {{:function, :__struct__, 0}, _, ["%Kernel.DocsTest.SampleDocs{}"],
               %{"en" => "My struct"}, %{}} = function_struct_0
 
@@ -259,6 +272,9 @@ defmodule Kernel.DocsTest do
       assert {{:macro, :is_zero, 1}, _, ["is_zero(v)"], %{"en" => "A guard"}, %{guard: true}} =
                guard_is_zero
 
+      assert {{:macrocallback, :macrocallback_multi, 1}, _, [],
+              %{"en" => "Macrocallback with multiple clauses"}, %{}} = macrocallback_multi
+
       assert {{:macrocallback, :qux, 1}, _, [], %{"en" => "Macrocallback doc"}, %{}} =
                macrocallback_qux
 

lib/iex/test/iex/helpers_test.exs

@@ -677,6 +677,13 @@ defmodule IEx.HelpersTest do
                @callback test(:foo) :: integer()
                @callback test(:bar) :: [integer()]
                """
+
+        assert capture_io(fn -> b(MultipleClauseCallback.test()) end) =~ """
+               @callback test(:foo) :: integer()
+               @callback test(:bar) :: [integer()]
+
+               callback
+               """
       end)
     after
       cleanup_modules([MultipleClauseCallback])