Remove specs which are pass through and from private modules

Author: josevalim

lib/eex/lib/eex.ex

@@ -125,7 +125,11 @@ defmodule EEx do
           | {:indentation, non_neg_integer}
           | {:trim, boolean()}
 
-  @type compile_opt :: tokenize_opt | {:engine, module()} | {:parser_options, Code.parser_opts()}
+  @type compile_opt ::
+          tokenize_opt
+          | {:engine, module()}
+          | {:parser_options, Code.parser_opts()}
+          | {atom(), term()}
 
   @doc """
   Generates a function definition from the given string.
@@ -137,6 +141,7 @@ defmodule EEx do
   template.
 
   The supported `options` are described [in the module docs](#module-options).
+  Additional options are passed to the underlying engine.
 
   ## Examples
 

lib/eex/lib/eex/compiler.ex

@@ -10,22 +10,6 @@ defmodule EEx.Compiler do
   @h_spaces [?\s, ?\t]
   @all_spaces [?\s, ?\t, ?\n, ?\r]
 
-  @typedoc """
-  Options for EEx compilation functions.
-
-  These options control various aspects of EEx template compilation including
-  file information, parsing behavior, and the template engine to use.
-  """
-  @type compile_opts :: [
-          file: String.t(),
-          line: pos_integer(),
-          column: pos_integer(),
-          indentation: non_neg_integer(),
-          trim: boolean(),
-          parser_options: Code.parser_opts(),
-          engine: module()
-        ]
-
   @doc """
   Tokenize EEx contents.
   """
@@ -306,7 +290,7 @@ defmodule EEx.Compiler do
   and the engine together by handling the tokens and invoking
   the engine every time a full expression or text is received.
   """
-  @spec compile([EEx.token()], String.t(), compile_opts) :: Macro.t()
+  @spec compile([EEx.token()], String.t(), keyword) :: Macro.t()
   def compile(tokens, source, opts) do
     file = opts[:file] || "nofile"
     line = opts[:line] || 1

lib/eex/lib/eex/engine.ex

@@ -14,29 +14,16 @@ defmodule EEx.Engine do
 
   @type state :: term
 
-  @typedoc """
-  Options passed to engine initialization.
-
-  These are the same options passed to `EEx.Compiler.compile/3`,
-  allowing engines to access compilation settings and customize
-  their behavior accordingly.
-  """
-  @type init_opts :: [
-          file: String.t(),
-          line: pos_integer(),
-          column: pos_integer(),
-          indentation: non_neg_integer(),
-          trim: boolean(),
-          parser_options: Code.parser_opts(),
-          engine: module()
-        ]
-
   @doc """
   Called at the beginning of every template.
 
+  It receives the options during compilation, including the
+  ones managed by EEx, such as `:line` and `:file`, as well
+  as custom engine options.
+
   It must return the initial state.
   """
-  @callback init(opts :: init_opts) :: state
+  @callback init(opts :: keyword) :: state
 
   @doc """
   Called at the end of every template.

lib/elixir/lib/code.ex

@@ -251,18 +251,27 @@ defmodule Code do
   @typedoc """
   Options for code formatting functions.
   """
-  @type format_opts :: [
-          file: binary(),
-          line: pos_integer(),
-          line_length: pos_integer(),
-          locals_without_parens: keyword(),
-          force_do_end_blocks: boolean(),
-          migrate: boolean(),
-          migrate_bitstring_modifiers: boolean(),
-          migrate_call_parens_on_pipe: boolean(),
-          migrate_charlists_as_sigils: boolean(),
-          migrate_unless: boolean()
-        ]
+  @type format_opt ::
+          {:file, binary()}
+          | {:line, pos_integer()}
+          | {:line_length, pos_integer()}
+          | {:locals_without_parens, keyword()}
+          | {:force_do_end_blocks, boolean()}
+          | {:migrate, boolean()}
+          | {:migrate_bitstring_modifiers, boolean()}
+          | {:migrate_call_parens_on_pipe, boolean()}
+          | {:migrate_charlists_as_sigils, boolean()}
+          | {:migrate_unless, boolean()}
+          | {atom(), term()}
+
+  @typedoc """
+  Options for `quoted_to_algebra/2`.
+  """
+  @type quoted_to_algebra_opt ::
+          {:line, pos_integer() | nil}
+          | {:escape, boolean()}
+          | {:locals_without_parens, keyword()}
+          | {:comments, [term()]}
 
   @typedoc """
   Options for parsing functions that convert strings to quoted expressions.
@@ -1079,7 +1088,7 @@ defmodule Code do
   address the deprecation warnings.
   """
   @doc since: "1.6.0"
-  @spec format_string!(binary, format_opts) :: iodata
+  @spec format_string!(binary, [format_opt]) :: iodata
   def format_string!(string, opts \\ []) when is_binary(string) and is_list(opts) do
     line_length = Keyword.get(opts, :line_length, 98)
 
@@ -1104,7 +1113,7 @@ defmodule Code do
   available options.
   """
   @doc since: "1.6.0"
-  @spec format_file!(binary, format_opts) :: iodata
+  @spec format_file!(binary, [format_opt]) :: iodata
   def format_file!(file, opts \\ []) when is_binary(file) and is_list(opts) do
     string = File.read!(file)
     formatted = format_string!(string, [file: file, line: 1] ++ opts)
@@ -1516,14 +1525,13 @@ defmodule Code do
       `string_to_quoted/2`, setting this option to `false` will prevent it from
       escaping the sequences twice. Defaults to `true`.
 
-  See `format_string!/2` for the full list of formatting options including 
+  See `format_string!/2` for the full list of formatting options including
   `:file`, `:line`, `:line_length`, `:locals_without_parens`, `:force_do_end_blocks`,
   `:syntax_colors`, and all migration options like `:migrate_charlists_as_sigils`.
   """
   @doc since: "1.13.0"
-  @spec quoted_to_algebra(Macro.t(), [
-          Code.Formatter.to_algebra_opt() | Code.Normalizer.normalize_opt()
-        ]) :: Inspect.Algebra.t()
+  @spec quoted_to_algebra(Macro.t(), [format_opt() | quoted_to_algebra_opt()]) ::
+          Inspect.Algebra.t()
   def quoted_to_algebra(quoted, opts \\ []) do
     quoted
     |> Code.Normalizer.normalize(opts)

lib/elixir/lib/code/formatter.ex

@@ -155,32 +155,10 @@ defmodule Code.Formatter do
 
   @do_end_keywords [:rescue, :catch, :else, :after]
 
-  @typedoc """
-  Options for `to_algebra/2`.
-
-  These options include all the standard code formatting options plus
-  additional context like comments and syntax highlighting colors.
-  """
-  @type to_algebra_opt ::
-          {:comments, [term()]}
-          | {:syntax_colors, keyword()}
-          | {:sigils, keyword()}
-          | {:file, binary()}
-          | {:line, pos_integer()}
-          | {:line_length, pos_integer()}
-          | {:locals_without_parens, keyword()}
-          | {:force_do_end_blocks, boolean()}
-          | {:migrate, boolean()}
-          | {:migrate_bitstring_modifiers, boolean()}
-          | {:migrate_call_parens_on_pipe, boolean()}
-          | {:migrate_charlists_as_sigils, boolean()}
-          | {:migrate_unless, boolean()}
-          | {atom(), term()}
-
   @doc """
   Converts the quoted expression into an algebra document.
   """
-  @spec to_algebra(Macro.t(), [to_algebra_opt]) :: Inspect.Algebra.t()
+  @spec to_algebra(Macro.t(), keyword()) :: Inspect.Algebra.t()
   def to_algebra(quoted, opts \\ []) do
     comments = Keyword.get(opts, :comments, [])
 

lib/elixir/lib/code/normalizer.ex

@@ -10,20 +10,11 @@ defmodule Code.Normalizer do
                   is_binary(x) or
                   is_atom(x)
 
-  @typedoc """
-  Options for `normalize/2`.
-  """
-  @type normalize_opt ::
-          {:line, pos_integer() | nil}
-          | {:escape, boolean()}
-          | {:locals_without_parens, keyword()}
-          | {atom(), term()}
-
   @doc """
   Wraps literals in the quoted expression to conform to the AST format expected
   by the formatter.
   """
-  @spec normalize(Macro.t(), [normalize_opt]) :: Macro.t()
+  @spec normalize(Macro.t(), keyword()) :: Macro.t()
   def normalize(quoted, opts \\ []) do
     line = Keyword.get(opts, :line, nil)
     escape = Keyword.get(opts, :escape, true)

lib/elixir/lib/io/ansi/docs.ex

@@ -44,7 +44,7 @@ defmodule IO.ANSI.Docs do
   Values for the color settings are strings with
   comma-separated ANSI values.
   """
-  @spec default_options() :: keyword
+  @spec default_options() :: print_opts
   def default_options do
     [
       enabled: true,

lib/elixir/lib/module/types/descr.ex

@@ -49,15 +49,6 @@ defmodule Module.Types.Descr do
   @empty_intersection [0, @none]
   @empty_difference [0, []]
 
-  # Type definitions
-
-  @typedoc """
-  Options for `to_quoted/2`.
-  """
-  @type to_quoted_opts :: [
-          collapse_structs: boolean()
-        ]
-
   defguard is_descr(descr) when is_map(descr) or descr == :term
 
   defp descr_key?(:term, _key), do: true
@@ -559,7 +550,6 @@ defmodule Module.Types.Descr do
     * `:collapse_structs` - do not show struct fields that match
       their default type
   """
-  @spec to_quoted(term(), to_quoted_opts) :: Macro.t()
   def to_quoted(descr, opts \\ []) do
     if term_type?(descr) do
       {:term, [], []}
@@ -634,7 +624,6 @@ defmodule Module.Types.Descr do
     * `:collapse_structs` - do not show struct fields that match
       their default type
   """
-  @spec to_quoted(term(), to_quoted_opts) :: String.t()
   def to_quoted_string(descr, opts \\ []) do
     descr
     |> to_quoted(opts)

lib/elixir/lib/module/types/helpers.ex

@@ -6,13 +6,6 @@ defmodule Module.Types.Helpers do
   # AST and enumeration helpers.
   @moduledoc false
 
-  @typedoc """
-  Options for `expr_to_string/2`.
-  """
-  @type expr_to_string_opts :: [
-          collapse_structs: boolean()
-        ]
-
   ## AST helpers
 
   @doc """
@@ -278,8 +271,11 @@ defmodule Module.Types.Helpers do
   translating inlined Erlang calls back to Elixir.
 
   We also undo some macro expressions done by the Kernel module.
+
+  ## Options
+
+    * `:collapse_structs` - when false, show structs full representation
   """
-  @spec expr_to_string(Macro.t(), expr_to_string_opts) :: String.t()
   def expr_to_string(expr, opts \\ []) do
     string = prewalk_expr_to_string(expr, opts)
 

lib/iex/lib/iex/broker.ex

@@ -9,13 +9,6 @@ defmodule IEx.Broker do
   @type take_ref :: {takeover_ref :: reference(), server_ref :: reference()}
   @type shell :: pid | nil
 
-  @typedoc """
-  Options for `take_over/3`.
-  """
-  @type take_over_opts :: [
-          evaluator: pid()
-        ]
-
   use GenServer
 
   ## Shell API
@@ -65,7 +58,7 @@ defmodule IEx.Broker do
   @doc """
   Client requests a takeover.
   """
-  @spec take_over(binary, iodata, take_over_opts) ::
+  @spec take_over(binary, iodata, keyword) ::
           {:ok, server :: pid, group_leader :: pid, counter :: integer}
           | {:error, :no_iex | :refused | atom()}
   def take_over(location, whereami, opts) do