Add correct line numbers to Erlang link warnings

Author: garazdawi

lib/ex_doc/autolink.ex

@@ -7,6 +7,9 @@ defmodule ExDoc.Autolink do
   # * `:current_module` - the module that the docs are being generated for. Used to link local
   #   calls and see if remote calls are in the same app.
   #
+  # * `:current_kfa` - the kind, function, arity that the docs are being generated for. Is nil
+  #    if there is no such thing. Used to generate more accurate warnings.
+  #
   # * `:module_id` - id of the module being documented (e.g.: `"String"`)
   #
   # * `:file` - source file location
@@ -48,6 +51,7 @@ defmodule ExDoc.Autolink do
     extras: [],
     deps: [],
     ext: ".html",
+    current_kfa: nil,
     siblings: [],
     skip_undefined_reference_warnings_on: [],
     skip_code_autolink_to: [],
@@ -495,7 +499,16 @@ defmodule ExDoc.Autolink do
     # TODO: Remove on Elixir v1.14
     stacktrace_info =
       if unquote(Version.match?(System.version(), ">= 1.14.0")) do
-        [file: config.file, line: config.line]
+        f =
+          case config.current_kfa do
+            {:function, f, a} ->
+              [function: {f, a}]
+
+            _ ->
+              []
+          end
+
+        [file: config.file, line: config.line, module: config.current_module] ++ f
       else
         []
       end

lib/ex_doc/formatter/html.ex

@@ -92,7 +92,15 @@ defmodule ExDoc.Formatter.HTML do
         docs =
           for child_node <- node.docs do
             id = id(node, child_node)
-            autolink_opts = autolink_opts ++ [id: id, line: child_node.doc_line]
+
+            autolink_opts =
+              autolink_opts ++
+                [
+                  id: id,
+                  line: child_node.doc_line,
+                  current_kfa: {:function, child_node.name, child_node.arity}
+                ]
+
             specs = Enum.map(child_node.specs, &language.autolink_spec(&1, autolink_opts))
             child_node = %{child_node | specs: specs}
             render_doc(child_node, language, autolink_opts, opts)
@@ -101,7 +109,14 @@ defmodule ExDoc.Formatter.HTML do
         typespecs =
           for child_node <- node.typespecs do
             id = id(node, child_node)
-            autolink_opts = autolink_opts ++ [id: id, line: child_node.doc_line]
+
+            autolink_opts =
+              autolink_opts ++
+                [
+                  id: id,
+                  line: child_node.doc_line,
+                  current_kfa: {child_node.type, child_node.name, child_node.arity}
+                ]
 
             child_node = %{
               child_node

lib/ex_doc/language/erlang.ex

@@ -262,6 +262,8 @@ defmodule ExDoc.Language.Erlang do
   end
 
   defp walk_doc({:code, attrs, [code], meta} = ast, config) when is_binary(code) do
+    config = %{config | line: meta[:line]}
+
     case Autolink.url(code, :regular_link, config) do
       url when is_binary(url) ->
         code = remove_prefix(code)

test/ex_doc/language/erlang_test.exs

@@ -350,21 +350,59 @@ defmodule ExDoc.Language.ErlangTest do
   describe "autolink_doc/2 for markdown warnings" do
     @describetag warnings: :send
 
+    test "bad function in module", c do
+      assert warn(
+               fn ->
+                 assert autolink_doc("\n`erlang_bar:bad/0`", c) ==
+                          ~s|<code class="inline">erlang_bar:bad/0</code>|
+               end,
+               line: 2
+             ) =~
+               ~s|documentation references function "erlang_bar:bad/0" but it is undefined or private|
+    end
+
+    test "bad type in module", c do
+      assert warn(
+               fn ->
+                 assert autolink_doc("\n`t:erlang_bar:bad/0`", c) ==
+                          ~s|<code class="inline">t:erlang_bar:bad/0</code>|
+               end,
+               line: 2
+             ) =~
+               ~s|documentation references type "t:erlang_bar:bad/0" but it is undefined or private|
+    end
+
+    test "bad callback in module", c do
+      assert warn(
+               fn ->
+                 assert autolink_doc("\n`c:erlang_bar:bad/0`", c) ==
+                          ~s|<code class="inline">c:erlang_bar:bad/0</code>|
+               end,
+               line: 2
+             ) =~ ~s|documentation references callback "c:erlang_bar:bad/0" but it is undefined|
+    end
+
     test "bad function in module ref", c do
-      assert warn(fn ->
-               assert autolink_doc("[Bad](`bad/0`)", c) == ~s|Bad|
-             end) =~ ~s|documentation references function "bad/0" but it is undefined or private|
+      assert warn(
+               fn ->
+                 assert autolink_doc("[Bad](`bad/0`)", c) == ~s|Bad|
+               end,
+               line: nil
+             ) =~ ~s|documentation references function "bad/0" but it is undefined or private|
     end
 
     test "linking to local extra works does not work", c do
-      assert warn(fn ->
-               assert autolink_doc("[extra](`e:extra.md`)", c) ==
-                        ~s|extra|
-             end) =~ ~r/documentation references "e:extra.md" but it is invalid/
+      assert warn(
+               fn ->
+                 assert autolink_doc("[extra](`e:extra.md`)", c) ==
+                          ~s|extra|
+               end,
+               line: nil
+             ) =~ ~r/documentation references "e:extra.md" but it is invalid/
     end
   end
 
-  describe "autolink_edoc/2 for extra" do
+  describe "autolink_doc/2 for extra" do
     test "function", c do
       assert autolink_extra("`erlang_foo:foo/0`", c) ==
                ~s|<a href="erlang_foo.html#foo/0"><code class="inline">erlang_foo:foo/0</code></a>|
@@ -410,9 +448,16 @@ defmodule ExDoc.Language.ErlangTest do
                ~s|<code class="inline">...a/0</code>|
     end
 
-    test "bad type", c do
-      assert autolink_extra("`t:bad:bad/0`", c) ==
-               ~s|<code class="inline">t:bad:bad/0</code>|
+    @tag warnings: :send
+    test "bad type ref", c do
+      assert warn(
+               fn ->
+                 assert autolink_extra("[t](`t:bad:bad/0`)", c) ==
+                          ~s|t|
+               end,
+               file: "extra.md",
+               line: nil
+             ) =~ ~s|documentation references type "t:bad:bad/0" but it is undefined or private|
     end
 
     test "bad module", c do
@@ -422,10 +467,14 @@ defmodule ExDoc.Language.ErlangTest do
 
     @tag warnings: :send
     test "bad module using m:", c do
-      assert warn(fn ->
-               assert autolink_extra("`m:does_not_exist`", c) ==
-                        ~s|<code class="inline">m:does_not_exist</code>|
-             end) =~ ~r|documentation references module \"does_not_exist\" but it is undefined|
+      assert warn(
+               fn ->
+                 assert autolink_extra("`m:does_not_exist`", c) ==
+                          ~s|<code class="inline">m:does_not_exist</code>|
+               end,
+               file: "extra.md",
+               line: 1
+             ) =~ ~r|documentation references module \"does_not_exist\" but it is undefined|
     end
 
     test "extras" do
@@ -618,7 +667,7 @@ defmodule ExDoc.Language.ErlangTest do
     [{:p, _, [ast], _}] = ExDoc.Markdown.to_ast(text, [])
 
     opts = c |> Map.take([:warnings]) |> Enum.to_list()
-    do_autolink_doc(ast, opts)
+    do_autolink_doc(ast, [file: "extra.md"] ++ opts)
   end
 
   defp autolink_doc(text, c, opts \\ []) do
@@ -637,6 +686,7 @@ defmodule ExDoc.Language.ErlangTest do
       ast,
       [
         current_module: :erlang_foo,
+        file: "erlang_foo.erl",
         module_id: "erlang_foo",
         deps: [foolib: "https://foolib.com"]
       ] ++
@@ -668,9 +718,18 @@ defmodule ExDoc.Language.ErlangTest do
     |> ExDoc.DocAST.to_string()
   end
 
-  defp warn(fun) when is_function(fun, 0) do
+  defp warn(fun, md \\ []) when is_function(fun, 0) do
     fun.()
-    assert_received {:warn, message, _metadata}
+    assert_received {:warn, message, metadata}
+
+    if Keyword.has_key?(md, :line) do
+      assert md[:line] == metadata[:line]
+    end
+
+    if Keyword.has_key?(md, :file) do
+      assert md[:file] == metadata[:file]
+    end
+
     message
   end