Improve docs and support column in IO.warn, closes #13179

Author: josevalim

lib/elixir/lib/io.ex

@@ -308,17 +308,20 @@ defmodule IO do
       entry from the compilation environment will be used
 
     * a keyword list with at least the `:file` option representing
-      a single stacktrace entry (since v1.14.0). The `:line`, `:module`,
-      `:function` options are also supported
+      a single stacktrace entry (since v1.14.0). The `:line`, `:column`,
+      `:module`, and `:function` options are also supported
 
-  This function also notifies the compiler a warning was printed
-  (in case --warnings-as-errors was enabled). It returns `:ok`
-  if it succeeds.
+  This function notifies the compiler a warning was printed
+  and emits a compiler diagnostic (`t:Code.diagnostic/1`).
+  The diagnostic will include precise file and location information
+  if a `Macro.Env` is given or those values have been passed as
+  keyword list, but not for stacktraces, as they are often imprecise.
+
+  It returns `:ok` if it succeeds.
 
   ## Examples
 
-      stacktrace = [{MyApp, :main, 1, [file: 'my_app.ex', line: 4]}]
-      IO.warn("variable bar is unused", stacktrace)
+      IO.warn("variable bar is unused", module: MyApp, function: {:main, 1}, line: 4, file: "my_app.ex")
       #=> warning: variable bar is unused
       #=>   my_app.ex:4: MyApp.main/1
 
@@ -337,15 +340,22 @@ defmodule IO do
 
   def warn(message, [{_, _} | _] = keyword) do
     if file = keyword[:file] do
-      warn(
-        message,
-        %{
+      line = keyword[:line]
+      column = keyword[:column]
+      position = if line && column, do: {line, column}, else: line
+      message = to_chardata(message)
+
+      stacktrace =
+        Macro.Env.stacktrace(%{
           __ENV__
           | module: keyword[:module],
             function: keyword[:function],
-            line: keyword[:line],
+            line: line,
             file: file
-        }
+        })
+
+      :elixir_errors.emit_diagnostic(:warning, position, file, message, stacktrace,
+        read_snippet: true
       )
     else
       warn(message, [])

lib/elixir/test/elixir/kernel/diagnostics_test.exs

@@ -769,6 +769,30 @@ defmodule Kernel.DiagnosticsTest do
       purge(Sample)
     end
 
+    @tag :tmp_dir
+    test "IO.warn file+line", %{tmp_dir: tmp_dir} do
+      path = make_relative_tmp(tmp_dir, "io-warn-file-line.ex")
+
+      source = """
+      IO.warn("oops\\nmulti\\nline", file: __ENV__.file, line: __ENV__.line)
+      """
+
+      File.write!(path, source)
+
+      expected = """
+          warning: oops
+          multi
+          line
+          │
+        1 │ IO.warn("oops\\nmulti\\nline", file: __ENV__.file, line: __ENV__.line)
+          │ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+          │
+          └─ tmp\
+      """
+
+      assert capture_io(:stderr, fn -> Code.eval_file(path) end) =~ expected
+    end
+
     @tag :tmp_dir
     test "IO.warn file+line+column", %{tmp_dir: tmp_dir} do
       path = make_relative_tmp(tmp_dir, "io-warn-file-line-column.ex")
@@ -785,7 +809,7 @@ defmodule Kernel.DiagnosticsTest do
           line
           │
         1 │ IO.warn("oops\\nmulti\\nline", file: __ENV__.file, line: __ENV__.line, column: 4)
-          │ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+          │    ~
           │
           └─ tmp\
       """