Improve unused type variable message, closes #10985

Author: josevalim

lib/elixir/lib/kernel/typespec.ex

@@ -1022,7 +1022,11 @@ defmodule Kernel.Typespec do
           :elixir_errors.erl_warn(caller.line, caller.file, warning)
 
         {_, :used_once} ->
-          compile_error(caller, "type variable #{name} is unused")
+          compile_error(
+            caller,
+            "type variable #{name} is used only once. Type variables in typespecs " <>
+              "must be referenced at least twice, otherwise it is equivalent to term()"
+          )
 
         _ ->
           :ok

lib/elixir/test/elixir/typespec_test.exs

@@ -133,7 +133,7 @@ defmodule TypespecTest do
     end
 
     test "type variable unused (singleton type variable)" do
-      assert_raise CompileError, ~r"type variable x is unused", fn ->
+      assert_raise CompileError, ~r"type variable x is used only once", fn ->
         test_module do
           @type foo(x) :: integer
         end
@@ -168,8 +168,8 @@ defmodule TypespecTest do
       end
     end
 
-    test "spec variable unused (singleton type variable)" do
-      assert_raise CompileError, ~r"type variable x is unused", fn ->
+    test "spec variable used only once (singleton type variable)" do
+      assert_raise CompileError, ~r"type variable x is used only once", fn ->
         test_module do
           @spec foo(x, integer) :: integer when x: var
           def foo(x, y), do: x + y