Unify position handling and improve docs

See #13179.
See #13184.

Author: josevalim

lib/elixir/lib/code.ex

@@ -196,21 +196,36 @@ defmodule Code do
 
   @typedoc """
   Diagnostics returned by the compiler and code evaluation.
+
+  If there is a file and position, then the diagnostic is precise
+  and you can use the given file and position for generating snippets,
+  IDEs annotations, and so on.
+
+  Otherwise, a stacktrace may be given, which you can place your own
+  heuristics to provide better reporting.
   """
   @type diagnostic(severity) :: %{
-          required(:file) => Path.t(),
+          required(:file) => Path.t() | nil,
           required(:severity) => severity,
           required(:message) => String.t(),
-          required(:position) => position,
+          required(:position) => position(),
           required(:stacktrace) => Exception.stacktrace(),
-          required(:span) => {non_neg_integer, non_neg_integer} | nil,
+          required(:span) => {non_neg_integer(), non_neg_integer()} | nil,
           optional(:exception) => Exception.t() | nil,
           optional(any()) => any()
         }
 
   @typedoc "The line. 0 indicates no line."
   @type line() :: non_neg_integer()
-  @type position() :: line() | {pos_integer(), column :: non_neg_integer}
+
+  @typedoc """
+  The position of the diagnostic.
+
+  Can be either a line number or a `{line, column}`.
+  Line and columns numbers are one-based.
+  A position of `0` represents unknown.
+  """
+  @type position() :: line() | {line :: pos_integer(), column :: pos_integer()}
 
   @boolean_compiler_options [
     :docs,

lib/mix/lib/mix/task.compiler.ex

@@ -31,13 +31,20 @@ defmodule Mix.Task.Compiler do
   defmodule Diagnostic do
     @moduledoc """
     Diagnostic information such as a warning or compilation error.
+
+    If there is a file and position, then the diagnostic is precise
+    and you can use the given file and position for generating snippets,
+    IDEs annotations, and so on.
+
+    Otherwise, a stacktrace may be given, which you can place your own
+    heuristics to provide better reporting.
     """
 
     @type t :: %__MODULE__{
-            file: Path.t(),
+            file: Path.t() | nil,
             severity: severity,
             message: IO.chardata(),
-            position: position,
+            position: Code.position(),
             compiler_name: String.t(),
             details: Exception.t() | any,
             stacktrace: Exception.stacktrace(),
@@ -61,21 +68,6 @@ defmodule Mix.Task.Compiler do
     """
     @type severity :: :error | :warning | :information | :hint
 
-    @typedoc """
-    Where in a file the diagnostic applies. Can be either a line number,
-    a `{line, column}` tuple, a range specified as `{start_line, start_col,
-    end_line, end_col}`. `0` line represents unknown.
-
-    Line numbers are one-based, and column numbers in a range are zero-based and refer
-    to the cursor position at the start of the character at that index. For example,
-    to indicate that a diagnostic applies to the first `n` characters of the
-    first line, the range would be `{1, 0, 1, n}`.
-    """
-    @type position ::
-            non_neg_integer
-            | {pos_integer, non_neg_integer}
-            | {pos_integer, non_neg_integer, pos_integer, non_neg_integer}
-
     @enforce_keys [:file, :severity, :message, :position, :compiler_name]
     defstruct [
       :file,