Give variables used alongside patterns high priority in signatures

Author: José Valim

lib/elixir/lib/module.ex

@@ -669,15 +669,23 @@ defmodule Module do
     {{:\\, [], [left, right]}, acc}
   end
 
-  defp simplify_signature({:=, _, [_, right]}, acc) do
-    simplify_signature(right, acc)
+  # If the variable is being used explicitly for naming,
+  # we always give it a higher priority (nil) even if it
+  # starts with underscore.
+  defp simplify_signature({:=, _, [{var, _, atom}, _]}, acc) when is_atom(atom) do
+    {simplify_var(var, nil), acc}
   end
 
+  defp simplify_signature({:=, _, [_, {var, _, atom}]}, acc) when is_atom(atom) do
+    {simplify_var(var, nil), acc}
+  end
+
+  # If we have only the varible as argument, it also gets
+  # higher priority. However, if the variable starts with
+  # underscore, we give it a secondary context (Elixir) with
+  # lower priority.
   defp simplify_signature({var, _, atom}, acc) when is_atom(atom) do
-    case Atom.to_string(var) do
-      "_" <> rest -> {{String.to_atom(rest), [], Elixir}, acc}
-      _           -> {{var, [], nil}, acc}
-    end
+    {simplify_var(var, Elixir), acc}
   end
 
   defp simplify_signature({:%, _, [left, _]}, acc) when is_atom(left) do
@@ -697,13 +705,21 @@ defmodule Module do
   defp simplify_signature(other, acc) when is_binary(other),  do: autogenerated(acc, :binary)
   defp simplify_signature(_, acc),                            do: autogenerated(acc, :arg)
 
+  defp simplify_var(var, guess_priority) do
+    case Atom.to_string(var) do
+      "_" -> {:_, [], guess_priority}
+      "_" <> rest -> {String.to_atom(rest), [], guess_priority}
+      _ -> {var, [], nil}
+    end
+  end
+
   defp simplify_module_name(module) when is_atom(module) do
     try do
       split(module)
     rescue
       ArgumentError -> module
     else
-      module_name -> String.to_atom(camelcase_to_underscore(List.last(module_name)))
+      module_name -> String.to_atom(Macro.underscore(List.last(module_name)))
     end
   end
 
@@ -737,15 +753,6 @@ defmodule Module do
     length(:lists.filter(fn(el) -> el == key end, list))
   end
 
-  defp camelcase_to_underscore(<<c::utf8, rest::binary>>) when c >= ?A and c <= ?Z,
-    do: do_camelcase_to_underscore(rest, <<c + 32::utf8>>)
-  defp do_camelcase_to_underscore(<<c::utf8, rest::binary>>, acc) when c >= ?A and c <= ?Z,
-    do: do_camelcase_to_underscore(rest, <<acc::binary, ?_, c + 32::utf8>>)
-  defp do_camelcase_to_underscore(<<c::utf8, rest::binary>>, acc),
-    do: do_camelcase_to_underscore(rest, <<acc::binary, c>>)
-  defp do_camelcase_to_underscore(<<>>, acc),
-    do: acc
-
   # Merge
 
   defp merge_signatures([h1 | t1], [h2 | t2], i) do
@@ -765,8 +772,8 @@ defmodule Module do
   end
 
   # The older signature, when given, always have higher precedence
-  defp merge_signature({_, _, nil} = older, _newer, _),        do: older
-  defp merge_signature(_older, {_, _, nil} = newer, _),        do: newer
+  defp merge_signature({_, _, nil} = older, _newer, _), do: older
+  defp merge_signature(_older, {_, _, nil} = newer, _), do: newer
 
   # Both are a guess, so check if they are the same guess
   defp merge_signature({var, _, _} = older, {var, _, _}, _), do: older

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

@@ -3,126 +3,147 @@ Code.require_file "../test_helper.exs", __DIR__
 defmodule Kernel.DocsTest do
   use ExUnit.Case
 
+  import PathHelpers
+
   test "attributes format" do
     defmodule DocAttributes do
       @moduledoc "Module doc"
       assert @moduledoc == "Module doc"
-      assert Module.get_attribute(__MODULE__, :moduledoc) == {8, "Module doc"}
+      assert Module.get_attribute(__MODULE__, :moduledoc) == {__ENV__.line - 2, "Module doc"}
 
       @typedoc "Type doc"
       assert @typedoc == "Type doc"
-      assert Module.get_attribute(__MODULE__, :typedoc) == {12, "Type doc"}
+      assert Module.get_attribute(__MODULE__, :typedoc) == {__ENV__.line - 2, "Type doc"}
       @type foobar :: any
 
       @doc "Function doc"
       assert @doc == "Function doc"
-      assert Module.get_attribute(__MODULE__, :doc) == {17, "Function doc"}
+      assert Module.get_attribute(__MODULE__, :doc) == {__ENV__.line - 2, "Function doc"}
       def foobar() do
         :ok
       end
     end
   end
 
-  test "compiled with docs" do
-    deftestmodule(SampleDocs)
-
-    docs = Code.get_docs(SampleDocs, :all)
-    assert Code.get_docs(SampleDocs, :docs) == docs[:docs]
-    assert Code.get_docs(SampleDocs, :moduledoc) == docs[:moduledoc]
-    assert Code.get_docs(SampleDocs, :type_docs) == docs[:type_docs]
-    assert Code.get_docs(SampleDocs, :callback_docs) == docs[:callback_docs]
-
-    assert [{{:arg_names, 5}, _, :def,
-             [{:list1, [], Elixir},
-              {:list2, [], Elixir},
-              {:map1, [], Elixir},
-              {:list3, [], Elixir},
-              {:map2, [], Elixir}], nil},
-            {{:foo, 1}, _, :def, [{:arg, [], nil}], "Function doc"},
-            {{:foobar, 0}, _, :def, [], nil},
-            {{:qux, 1}, _, :def, [{:bool, [], Elixir}], false},
-            {{:with_defaults, 4}, _, :def,
-             [{:int, [], Elixir},
-              {:\\, [], [{:arg, [], nil}, 0]},
-              {:\\, [], [{:year, [], nil}, 2015]},
-              {:\\, [], [{:fun, [], nil}, {:&, _, [{:/, _, [{:>=, _, nil}, 2]}]}]}], nil}] = docs[:docs]
-
-    assert {_, "Module doc"} = docs[:moduledoc]
-
-    assert [{{:bar, 1}, _, :opaque, "Opaque type doc"},
-            {{:foo, 1}, _, :type, "Type doc"}] = docs[:type_docs]
-
-    assert [{{:bar, 0}, _, :callback, false},
-            {{:baz, 2}, _, :callback, nil},
-            {{:foo, 1}, _, :callback, "Callback doc"},
-            {{:qux, 1}, _, :macrocallback, "Macrocallback doc"}] = docs[:callback_docs]
-  end
-
   test "compiled without docs" do
     Code.compiler_options(docs: false)
 
-    deftestmodule(WithoutSampleDocs)
+    write_beam(defmodule WithoutDocs do
+      @moduledoc "Module doc"
 
-    assert Code.get_docs(WithoutSampleDocs, :docs) == nil
-    assert Code.get_docs(WithoutSampleDocs, :moduledoc) == nil
-    assert Code.get_docs(WithoutSampleDocs, :type_docs) == nil
-    assert Code.get_docs(WithoutSampleDocs, :callback_docs) == nil
+      @doc "Some doc"
+      def foobar(arg), do: arg
+    end)
+
+    assert Code.get_docs(WithoutDocs, :docs) == nil
+    assert Code.get_docs(WithoutDocs, :moduledoc) == nil
+    assert Code.get_docs(WithoutDocs, :type_docs) == nil
+    assert Code.get_docs(WithoutDocs, :callback_docs) == nil
   after
     Code.compiler_options(docs: true)
   end
 
   test "compiled in memory does not have accessible docs" do
-    defmodule WithoutDocs do
+    defmodule InMemoryDocs do
       @moduledoc "Module doc"
 
       @doc "Some doc"
       def foobar(arg), do: arg
     end
 
-    assert Code.get_docs(NoDocs, :docs) == nil
-    assert Code.get_docs(NoDocs, :moduledoc) == nil
-    assert Code.get_docs(NoDocs, :callback_docs) == nil
+    assert Code.get_docs(InMemoryDocs, :docs) == nil
+    assert Code.get_docs(InMemoryDocs, :moduledoc) == nil
+    assert Code.get_docs(InMemoryDocs, :callback_docs) == nil
   end
 
-  defp deftestmodule(name) do
-    import PathHelpers
+  describe "compiled with docs" do
+    test "infers signatures" do
+      write_beam(defmodule SignatureDocs do
+        def arg_names([], [], %{}, [], %{}), do: false
+
+        @year 2015
+        def with_defaults(@year, arg \\ 0, year \\ @year, fun \\ &>=/2) do
+          {fun, arg + year}
+        end
+
+        def with_struct(%URI{}), do: :ok
+
+        def with_underscore({_, _} = _two_tuple), do: :ok
+        def with_underscore(_), do: :error
+
+        def only_underscore(_), do: :ok
+
+        def two_good_names(first, :ok), do: first
+        def two_good_names(second, :error), do: second
+      end)
+
+      assert [{{:arg_names, 5}, _, :def,
+              [{:list1, _, Elixir},
+               {:list2, _, Elixir},
+               {:map1, _, Elixir},
+               {:list3, _, Elixir},
+               {:map2, _, Elixir}], nil},
+             {{:only_underscore, 1}, _, :def,
+              [{:_, _, Elixir}], nil},
+             {{:two_good_names, 2}, _, :def,
+              [{:first, _, nil},
+               {:atom, _, Elixir}], nil},
+             {{:with_defaults, 4}, _, :def,
+              [{:int, _, Elixir},
+               {:\\, _, [{:arg, _, nil}, 0]},
+               {:\\, _, [{:year, _, nil}, 2015]},
+               {:\\, _, [{:fun, _, nil}, {:&, _, [{:/, _, [{:>=, _, nil}, 2]}]}]}], nil},
+             {{:with_struct, 1}, _, :def, [{:uri, _, Elixir}], nil},
+             {{:with_underscore, 1}, _, :def, [{:two_tuple, _, nil}], nil}] = Code.get_docs(SignatureDocs, :docs)
+    end
 
-    write_beam(defmodule name do
-      @moduledoc "Module doc"
+    test "includes docs for functions, modules, types and callbacks" do
+      write_beam(defmodule SampleDocs do
+        @moduledoc "Module doc"
 
-      @typedoc "Type doc"
-      @type foo(any) :: any
+        @typedoc "Type doc"
+        @type foo(any) :: any
 
-      @typedoc "Opaque type doc"
-      @opaque bar(any) :: any
+        @typedoc "Opaque type doc"
+        @opaque bar(any) :: any
 
-      @doc "Callback doc"
-      @callback foo(any) :: any
+        @doc "Callback doc"
+        @callback foo(any) :: any
 
-      @doc false
-      @callback bar() :: term
+        @doc false
+        @callback bar() :: term
+        @callback baz(any, term) :: any
 
-      @callback baz(any, term) :: any
+        @doc "Macrocallback doc"
+        @macrocallback qux(any) :: any
 
-      @doc "Macrocallback doc"
-      @macrocallback qux(any) :: any
+        @doc "Function doc"
+        def foo(arg) do
+          arg + 1
+        end
 
-      @doc "Function doc"
-      def foo(arg) do
-        arg + 1
-      end
+        @doc false
+        def bar(true), do: false
+      end)
 
-      @doc false
-      def qux(true), do: false
+      docs = Code.get_docs(SampleDocs, :all)
+      assert Code.get_docs(SampleDocs, :docs) == docs[:docs]
+      assert Code.get_docs(SampleDocs, :moduledoc) == docs[:moduledoc]
+      assert Code.get_docs(SampleDocs, :type_docs) == docs[:type_docs]
+      assert Code.get_docs(SampleDocs, :callback_docs) == docs[:callback_docs]
 
-      def foobar(), do: nil
+      assert [{{:bar, 1}, _, :def, [{:bool, _, Elixir}], false},
+              {{:foo, 1}, _, :def, [{:arg, _, nil}], "Function doc"}] = docs[:docs]
 
-      def arg_names([], [], %{}, [], %{}), do: false
+      assert {_, "Module doc"} = docs[:moduledoc]
 
-      @year 2015
-      def with_defaults(@year, arg \\ 0, year \\ @year, fun \\ &>=/2) do
-        {fun, arg + year}
-      end
-    end)
+      assert [{{:bar, 1}, _, :opaque, "Opaque type doc"},
+              {{:foo, 1}, _, :type, "Type doc"}] = docs[:type_docs]
+
+      assert [{{:bar, 0}, _, :callback, false},
+              {{:baz, 2}, _, :callback, nil},
+              {{:foo, 1}, _, :callback, "Callback doc"},
+              {{:qux, 1}, _, :macrocallback, "Macrocallback doc"}] = docs[:callback_docs]
+    end
   end
 end