Replace keyword with concrete keyword lists in specs for all functions taking options argument

Add missing documentation for some of the supported options
Add specs for functions with options argumnet

Author: lukaszsamson

lib/eex/lib/eex.ex

@@ -118,6 +118,15 @@ defmodule EEx do
           | {:expr | :start_expr | :middle_expr | :end_expr, marker, charlist, metadata}
           | {:eof, metadata}
 
+  @type tokenize_opt ::
+          {:file, binary()}
+          | {:line, line}
+          | {:column, column}
+          | {:indentation, non_neg_integer}
+          | {:trim, boolean()}
+
+  @type compile_opt :: tokenize_opt | {:engine, module()} | {:parser_options, Code.parser_opts()}
+
   @doc """
   Generates a function definition from the given string.
 
@@ -220,7 +229,7 @@ defmodule EEx do
       "3"
 
   """
-  @spec compile_string(String.t(), keyword) :: Macro.t()
+  @spec compile_string(String.t(), [compile_opt]) :: Macro.t()
   def compile_string(source, options \\ []) when is_binary(source) and is_list(options) do
     case tokenize(source, options) do
       {:ok, tokens} ->
@@ -259,7 +268,7 @@ defmodule EEx do
       #=> "3"
 
   """
-  @spec compile_file(Path.t(), keyword) :: Macro.t()
+  @spec compile_file(Path.t(), [compile_opt]) :: Macro.t()
   def compile_file(filename, options \\ []) when is_list(options) do
     filename = IO.chardata_to_string(filename)
     options = Keyword.merge([file: filename, line: 1], options)
@@ -277,7 +286,7 @@ defmodule EEx do
       "foo baz"
 
   """
-  @spec eval_string(String.t(), keyword, keyword) :: String.t()
+  @spec eval_string(String.t(), keyword, [compile_opt]) :: String.t()
   def eval_string(source, bindings \\ [], options \\ [])
       when is_binary(source) and is_list(bindings) and is_list(options) do
     compiled = compile_string(source, options)
@@ -299,7 +308,7 @@ defmodule EEx do
       #=> "foo baz"
 
   """
-  @spec eval_file(Path.t(), keyword, keyword) :: String.t()
+  @spec eval_file(Path.t(), keyword, [compile_opt]) :: String.t()
   def eval_file(filename, bindings \\ [], options \\ [])
       when is_list(bindings) and is_list(options) do
     filename = IO.chardata_to_string(filename)
@@ -339,7 +348,7 @@ defmodule EEx do
   Note new tokens may be added in the future.
   """
   @doc since: "1.14.0"
-  @spec tokenize([char()] | String.t(), opts :: keyword) ::
+  @spec tokenize([char()] | String.t(), [tokenize_opt]) ::
           {:ok, [token()]} | {:error, String.t(), metadata()}
   def tokenize(contents, opts \\ []) do
     EEx.Compiler.tokenize(contents, opts)

lib/eex/lib/eex/compiler.ex

@@ -10,6 +10,22 @@ 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.
   """
@@ -290,7 +306,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(), keyword) :: Macro.t()
+  @spec compile([EEx.token()], String.t(), compile_opts) :: Macro.t()
   def compile(tokens, source, opts) do
     file = opts[:file] || "nofile"
     line = opts[:line] || 1

lib/eex/lib/eex/engine.ex

@@ -14,12 +14,29 @@ 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 must return the initial state.
   """
-  @callback init(opts :: keyword) :: state
+  @callback init(opts :: init_opts) :: state
 
   @doc """
   Called at the end of every template.

lib/elixir/lib/calendar.ex

@@ -162,6 +162,22 @@ defmodule Calendar do
   """
   @type time_zone_database :: module()
 
+  @typedoc """
+  Options for formatting dates and times with `strftime/3`.
+  """
+  @type strftime_opts :: [
+          preferred_datetime: String.t(),
+          preferred_date: String.t(),
+          preferred_time: String.t(),
+          am_pm_names: (:am | :pm -> String.t()) | (:am | :pm, map() -> String.t()),
+          month_names: (pos_integer() -> String.t()) | (pos_integer(), map() -> String.t()),
+          abbreviated_month_names:
+            (pos_integer() -> String.t()) | (pos_integer(), map() -> String.t()),
+          day_of_week_names: (pos_integer() -> String.t()) | (pos_integer(), map() -> String.t()),
+          abbreviated_day_of_week_names:
+            (pos_integer() -> String.t()) | (pos_integer(), map() -> String.t())
+        ]
+
   @doc """
   Returns how many days there are in the given month of the given year.
   """
@@ -617,7 +633,7 @@ defmodule Calendar do
 
   """
   @doc since: "1.11.0"
-  @spec strftime(map(), String.t(), keyword()) :: String.t()
+  @spec strftime(map(), String.t(), strftime_opts()) :: String.t()
   def strftime(date_or_time_or_datetime, string_format, user_options \\ [])
       when is_map(date_or_time_or_datetime) and is_binary(string_format) do
     parse(

lib/elixir/lib/calendar/duration.ex

@@ -161,6 +161,22 @@ defmodule Duration do
   """
   @type duration :: t | [unit_pair]
 
+  @typedoc """
+  Options for `Duration.to_string/2`.
+  """
+  @type to_string_opts :: [
+          units: [
+            year: String.t(),
+            month: String.t(),
+            week: String.t(),
+            day: String.t(),
+            hour: String.t(),
+            minute: String.t(),
+            second: String.t()
+          ],
+          separator: String.t()
+        ]
+
   @microseconds_per_second 1_000_000
 
   @doc """
@@ -436,6 +452,7 @@ defmodule Duration do
 
   """
   @doc since: "1.18.0"
+  @spec to_string(t, to_string_opts) :: String.t()
   def to_string(%Duration{} = duration, opts \\ []) do
     units = Keyword.get(opts, :units, [])
     separator = Keyword.get(opts, :separator, " ")

lib/elixir/lib/code.ex

@@ -248,6 +248,49 @@ defmodule Code do
   """
   @type position() :: line() | {line :: pos_integer(), column :: pos_integer()}
 
+  @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()
+        ]
+
+  @typedoc """
+  Options for parsing functions that convert strings to quoted expressions.
+  """
+  @type parser_opts :: [
+          file: binary(),
+          line: pos_integer(),
+          column: pos_integer(),
+          indentation: non_neg_integer(),
+          columns: boolean(),
+          unescape: boolean(),
+          existing_atoms_only: boolean(),
+          token_metadata: boolean(),
+          literal_encoder: (term(), Macro.metadata() -> term()),
+          static_atoms_encoder: (atom() -> term()),
+          emit_warnings: boolean()
+        ]
+
+  @typedoc """
+  Options for environment evaluation functions like eval_string/3 and eval_quoted/3.
+  """
+  @type env_eval_opts :: [
+          file: binary(),
+          line: pos_integer(),
+          module: module(),
+          prune_binding: boolean()
+        ]
+
   @boolean_compiler_options [
     :docs,
     :debug_info,
@@ -560,7 +603,7 @@ defmodule Code do
       [a: 1, b: 2]
 
   """
-  @spec eval_string(List.Chars.t(), binding, Macro.Env.t() | keyword) :: {term, binding}
+  @spec eval_string(List.Chars.t(), binding, Macro.Env.t() | env_eval_opts) :: {term, binding}
   def eval_string(string, binding \\ [], opts \\ [])
 
   def eval_string(string, binding, %Macro.Env{} = env) do
@@ -615,7 +658,8 @@ defmodule Code do
 
   """
   @doc since: "1.15.0"
-  @spec with_diagnostics(keyword(), (-> result)) :: {result, [diagnostic(:warning | :error)]}
+  @spec with_diagnostics([log: boolean()], (-> result)) ::
+          {result, [diagnostic(:warning | :error)]}
         when result: term()
   def with_diagnostics(opts \\ [], fun) do
     value = :erlang.get(:elixir_code_diagnostics)
@@ -648,7 +692,7 @@ defmodule Code do
       Defaults to `true`.
   """
   @doc since: "1.15.0"
-  @spec print_diagnostic(diagnostic(:warning | :error), keyword()) :: :ok
+  @spec print_diagnostic(diagnostic(:warning | :error), snippet: boolean()) :: :ok
   def print_diagnostic(diagnostic, opts \\ []) do
     read_snippet? = Keyword.get(opts, :snippet, true)
     :elixir_errors.print_diagnostic(diagnostic, read_snippet?)
@@ -1035,7 +1079,7 @@ defmodule Code do
   address the deprecation warnings.
   """
   @doc since: "1.6.0"
-  @spec format_string!(binary, keyword) :: iodata
+  @spec format_string!(binary, format_opts) :: iodata
   def format_string!(string, opts \\ []) when is_binary(string) and is_list(opts) do
     line_length = Keyword.get(opts, :line_length, 98)
 
@@ -1060,7 +1104,7 @@ defmodule Code do
   available options.
   """
   @doc since: "1.6.0"
-  @spec format_file!(binary, keyword) :: iodata
+  @spec format_file!(binary, format_opts) :: 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)
@@ -1098,7 +1142,7 @@ defmodule Code do
       [a: 1, b: 2]
 
   """
-  @spec eval_quoted(Macro.t(), binding, Macro.Env.t() | keyword) :: {term, binding}
+  @spec eval_quoted(Macro.t(), binding, Macro.Env.t() | env_eval_opts) :: {term, binding}
   def eval_quoted(quoted, binding \\ [], env_or_opts \\ []) do
     {value, binding, _env} =
       eval_verify(:eval_quoted, [quoted, binding, env_for_eval(env_or_opts)])
@@ -1129,8 +1173,15 @@ defmodule Code do
     * `:line` - the line on which the script starts
 
     * `:module` - the module to run the environment on
+
+    * `:prune_binding` - (since v1.14.2) prune binding to keep only
+      variables read or written by the evaluated code. Note that
+      variables used by modules are always pruned, even if later used
+      by the modules. You can submit to the `:on_module` tracer event
+      and access the variables used by the module from its environment.
   """
   @doc since: "1.14.0"
+  @spec env_for_eval(Macro.Env.t() | env_eval_opts) :: Macro.Env.t()
   def env_for_eval(env_or_opts), do: :elixir.env_for_eval(env_or_opts)
 
   @doc """
@@ -1144,15 +1195,11 @@ defmodule Code do
 
   ## Options
 
-    * `:prune_binding` - (since v1.14.2) prune binding to keep only
-      variables read or written by the evaluated code. Note that
-      variables used by modules are always pruned, even if later used
-      by the modules. You can submit to the `:on_module` tracer event
-      and access the variables used by the module from its environment.
+  It accepts the same options as `env_for_eval/1`.
 
   """
   @doc since: "1.14.0"
-  @spec eval_quoted_with_env(Macro.t(), binding, Macro.Env.t(), keyword) ::
+  @spec eval_quoted_with_env(Macro.t(), binding, Macro.Env.t(), env_eval_opts) ::
           {term, binding, Macro.Env.t()}
   def eval_quoted_with_env(quoted, binding, %Macro.Env{} = env, opts \\ [])
       when is_list(binding) do
@@ -1263,7 +1310,7 @@ defmodule Code do
       {:error, {[line: 1, column: 4], "syntax error before: ", "\"3\""}}
 
   """
-  @spec string_to_quoted(List.Chars.t(), keyword) ::
+  @spec string_to_quoted(List.Chars.t(), parser_opts) ::
           {:ok, Macro.t()} | {:error, {location :: keyword, binary | {binary, binary}, binary}}
   def string_to_quoted(string, opts \\ []) when is_list(opts) do
     file = Keyword.get(opts, :file, "nofile")
@@ -1290,7 +1337,7 @@ defmodule Code do
 
   Check `string_to_quoted/2` for options information.
   """
-  @spec string_to_quoted!(List.Chars.t(), keyword) :: Macro.t()
+  @spec string_to_quoted!(List.Chars.t(), parser_opts) :: Macro.t()
   def string_to_quoted!(string, opts \\ []) when is_list(opts) do
     file = Keyword.get(opts, :file, "nofile")
     line = Keyword.get(opts, :line, 1)
@@ -1341,7 +1388,7 @@ defmodule Code do
 
   """
   @doc since: "1.13.0"
-  @spec string_to_quoted_with_comments(List.Chars.t(), keyword) ::
+  @spec string_to_quoted_with_comments(List.Chars.t(), parser_opts) ::
           {:ok, Macro.t(), list(map())} | {:error, {location :: keyword, term, term}}
   def string_to_quoted_with_comments(string, opts \\ []) when is_list(opts) do
     charlist = to_charlist(string)
@@ -1371,7 +1418,7 @@ defmodule Code do
   Check `string_to_quoted/2` for options information.
   """
   @doc since: "1.13.0"
-  @spec string_to_quoted_with_comments!(List.Chars.t(), keyword) :: {Macro.t(), list(map())}
+  @spec string_to_quoted_with_comments!(List.Chars.t(), parser_opts) :: {Macro.t(), list(map())}
   def string_to_quoted_with_comments!(string, opts \\ []) do
     charlist = to_charlist(string)
 
@@ -1456,6 +1503,9 @@ defmodule Code do
 
   ## Options
 
+  This function accepts all options supported by `format_string!/2` for controlling
+  code formatting, plus these additional options:
+
     * `:comments` - the list of comments associated with the quoted expression.
       Defaults to `[]`. It is recommended that both `:token_metadata` and
       `:literal_encoder` options are given to `string_to_quoted_with_comments/2`
@@ -1466,17 +1516,14 @@ defmodule Code do
       `string_to_quoted/2`, setting this option to `false` will prevent it from
       escaping the sequences twice. Defaults to `true`.
 
-    * `:locals_without_parens` - a keyword list of name and arity
-      pairs that should be kept without parens whenever possible.
-      The arity may be the atom `:*`, which implies all arities of
-      that name. The formatter already includes a list of functions
-      and this option augments this list.
-
-    * `:syntax_colors` - a keyword list of colors the output is colorized.
-      See `Inspect.Opts` for more information.
+  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(), keyword) :: Inspect.Algebra.t()
+  @spec quoted_to_algebra(Macro.t(), [
+          Code.Formatter.to_algebra_opt() | Code.Normalizer.normalize_opt()
+        ]) :: Inspect.Algebra.t()
   def quoted_to_algebra(quoted, opts \\ []) do
     quoted
     |> Code.Normalizer.normalize(opts)