Add @since documentation for 1.4 release (elixir-lang#7238)

This adds the `@since` attribute, documenting what new functions were
added in the 1.4 release.

lib/elixir/lib/calendar/date.ex

@@ -115,6 +115,7 @@ defmodule Date do
       true
 
   """
+  @since "1.4.0"
   @spec utc_today(Calendar.calendar()) :: t
   def utc_today(calendar \\ Calendar.ISO)
 
@@ -146,6 +147,7 @@ defmodule Date do
       true
 
   """
+  @since "1.4.0"
   @spec leap_year?(Calendar.date()) :: boolean()
   def leap_year?(date)
 
@@ -166,6 +168,7 @@ defmodule Date do
       29
 
   """
+  @since "1.4.0"
   @spec days_in_month(Calendar.date()) :: Calendar.day()
   def days_in_month(date)
 
@@ -398,6 +401,7 @@ defmodule Date do
       :eq
 
   """
+  @since "1.4.0"
   @spec compare(Calendar.date(), Calendar.date()) :: :lt | :eq | :gt
   def compare(%{calendar: calendar} = date1, %{calendar: calendar} = date2) do
     %{year: year1, month: month1, day: day1} = date1
@@ -591,6 +595,7 @@ defmodule Date do
       2
 
   """
+  @since "1.4.0"
   @spec day_of_week(Calendar.date()) :: non_neg_integer()
   def day_of_week(date)
 

lib/elixir/lib/calendar/datetime.ex

@@ -186,6 +186,7 @@ defmodule DateTime do
       #DateTime<2016-05-24 13:26:08.003Z>
 
   """
+  @since "1.4.0"
   @spec from_naive(NaiveDateTime.t(), Calendar.time_zone()) :: {:ok, t}
   def from_naive(naive_datetime, time_zone)
 
@@ -231,6 +232,7 @@ defmodule DateTime do
       #DateTime<2016-05-24 13:26:08.003Z>
 
   """
+  @since "1.4.0"
   @spec from_naive!(NaiveDateTime.t(), Calendar.time_zone()) :: t
   def from_naive!(naive_datetime, time_zone) do
     case from_naive(naive_datetime, time_zone) do
@@ -504,6 +506,7 @@ defmodule DateTime do
       {:error, :invalid_format}
 
   """
+  @since "1.4.0"
   @spec from_iso8601(String.t(), Calendar.calendar()) ::
           {:ok, t, Calendar.utc_offset()} | {:error, atom}
   def from_iso8601(string, calendar \\ Calendar.ISO) when is_binary(string) do
@@ -629,6 +632,7 @@ defmodule DateTime do
       :gt
 
   """
+  @since "1.4.0"
   @spec compare(Calendar.datetime(), Calendar.datetime()) :: :lt | :eq | :gt
   def compare(
         %{calendar: _, utc_offset: utc_offset1, std_offset: std_offset1} = datetime1,

lib/elixir/lib/calendar/naive_datetime.ex

@@ -96,6 +96,7 @@ defmodule NaiveDateTime do
       true
 
   """
+  @since "1.4.0"
   @spec utc_now(Calendar.calendar()) :: t
   def utc_now(calendar \\ Calendar.ISO)
 
@@ -239,6 +240,7 @@ defmodule NaiveDateTime do
       ~N[2014-10-02 00:29:10]
 
   """
+  @since "1.4.0"
   @spec add(t, integer, System.time_unit()) :: t
   def add(%NaiveDateTime{} = naive_datetime, integer, unit \\ :second)
       when is_integer(integer) do
@@ -275,6 +277,7 @@ defmodule NaiveDateTime do
       63579428950
 
   """
+  @since "1.4.0"
   @spec diff(t, t, System.time_unit()) :: integer
   def diff(%NaiveDateTime{} = ndatetime1, %NaiveDateTime{} = ndatetime2, unit \\ :second) do
     if not Calendar.compatible_calendars?(ndatetime1.calendar, ndatetime2.calendar) do
@@ -685,6 +688,7 @@ defmodule NaiveDateTime do
       :lt
 
   """
+  @since "1.4.0"
   @spec compare(Calendar.naive_datetime(), Calendar.naive_datetime()) :: :lt | :eq | :gt
   def compare(%{calendar: calendar1} = naive_datetime1, %{calendar: calendar2} = naive_datetime2) do
     if Calendar.compatible_calendars?(calendar1, calendar2) do

lib/elixir/lib/calendar/time.ex

@@ -55,6 +55,7 @@ defmodule Time do
       true
 
   """
+  @since "1.4.0"
   @spec utc_now(Calendar.calendar()) :: t
   def utc_now(calendar \\ Calendar.ISO) do
     {:ok, _, time, microsecond} = Calendar.ISO.from_unix(:os.system_time(), :native)
@@ -433,6 +434,7 @@ defmodule Time do
       :gt
 
   """
+  @since "1.4.0"
   @spec compare(Calendar.time(), Calendar.time()) :: :lt | :eq | :gt
   def compare(%{calendar: calendar} = time1, %{calendar: calendar} = time2) do
     %{hour: hour1, minute: minute1, second: second1, microsecond: {microsecond1, _}} = time1

lib/elixir/lib/enum.ex

@@ -1330,6 +1330,7 @@ defmodule Enum do
       [1001, 1002, 1003]
 
   """
+  @since "1.4.0"
   @spec map_every(t, non_neg_integer, (element -> any)) :: list
   def map_every(enumerable, nth, fun)
 
@@ -1730,6 +1731,7 @@ defmodule Enum do
       {[], []}
 
   """
+  @since "1.4.0"
   @spec split_with(t, (element -> any)) :: {list, list}
   def split_with(enumerable, fun) do
     {acc1, acc2} =
@@ -2737,6 +2739,7 @@ defmodule Enum do
       [{1, :a}, {2, :b}, {3, :c}]
 
   """
+  @since "1.4.0"
   @spec zip([t]) :: t
   @spec zip(t) :: t
 

lib/elixir/lib/float.ex

@@ -379,6 +379,7 @@ defmodule Float do
       {-16, 1}
 
   """
+  @since "1.4.0"
   def ratio(float) when is_float(float) do
     <<sign::1, exp::11, significant::52-bitstring>> = <<float::float>>
     {num, _, den} = decompose(significant)

lib/elixir/lib/inspect/algebra.ex

@@ -523,6 +523,7 @@ defmodule Inspect.Algebra do
   @doc ~S"""
   Colors a document if the `color_key` has a color in the options.
   """
+  @since "1.4.0"
   @spec color(t, Inspect.Opts.color_key(), Inspect.Opts.t()) :: doc_color
   def color(doc, color_key, %Inspect.Opts{syntax_colors: syntax_colors}) when is_doc(doc) do
     if precolor = Keyword.get(syntax_colors, color_key) do

lib/elixir/lib/integer.ex

@@ -72,6 +72,7 @@ defmodule Integer do
       -2
 
   """
+  @since "1.4.0"
   @spec mod(integer, neg_integer | pos_integer) :: integer
   def mod(dividend, divisor) do
     remainder = rem(dividend, divisor)
@@ -105,6 +106,7 @@ defmodule Integer do
       -50
 
   """
+  @since "1.4.0"
   @spec floor_div(integer, neg_integer | pos_integer) :: integer
   def floor_div(dividend, divisor) do
     if dividend * divisor < 0 and rem(dividend, divisor) != 0 do

lib/elixir/lib/list.ex

@@ -647,6 +647,7 @@ defmodule List do
       {3, [1, 2]}
 
   """
+  @since "1.4.0"
   @spec pop_at(list, integer, any) :: {any, list}
   def pop_at(list, index, default \\ nil) when is_integer(index) do
     if index < 0 do
@@ -863,6 +864,7 @@ defmodule List do
       [eq: [1], del: [4], eq: [2, 3], ins: [4]]
 
   """
+  @since "1.4.0"
   @spec myers_difference(list, list) :: [{:eq | :ins | :del, list}] | nil
   def myers_difference(list1, list2) when is_list(list1) and is_list(list2) do
     path = {0, 0, list1, list2, []}

lib/elixir/lib/regex.ex

@@ -179,6 +179,7 @@ defmodule Regex do
   This checks the version stored in the regular expression
   and recompiles the regex in case of version mismatch.
   """
+  @since "1.4.0"
   @spec recompile(t) :: t
   def recompile(%Regex{} = regex) do
     version = version()
@@ -197,6 +198,7 @@ defmodule Regex do
   @doc """
   Recompiles the existing regular expression and raises `Regex.CompileError` in case of errors.
   """
+  @since "1.4.0"
   @spec recompile!(t) :: t
   def recompile!(regex) do
     case recompile(regex) do
@@ -208,6 +210,7 @@ defmodule Regex do
   @doc """
   Returns the version of the underlying Regex engine.
   """
+  @since "1.4.0"
   # TODO: No longer check for function_exported? on OTP 20+.
   def version do
     if function_exported?(:re, :version, 0) do

lib/elixir/lib/registry.ex

@@ -174,6 +174,7 @@ defmodule Registry do
   ## Via callbacks
 
   @doc false
+  @since "1.4.0"
   def whereis_name({registry, key}) do
     case key_info!(registry) do
       {:unique, partitions, key_ets} ->
@@ -193,6 +194,7 @@ defmodule Registry do
   end
 
   @doc false
+  @since "1.4.0"
   def register_name({registry, key}, pid) when pid == self() do
     case register(registry, key, nil) do
       {:ok, _} -> :yes
@@ -201,6 +203,7 @@ defmodule Registry do
   end
 
   @doc false
+  @since "1.4.0"
   def send({registry, key}, msg) do
     case lookup(registry, key) do
       [{pid, _}] -> Kernel.send(pid, msg)
@@ -209,6 +212,7 @@ defmodule Registry do
   end
 
   @doc false
+  @since "1.4.0"
   def unregister_name({registry, key}) do
     unregister(registry, key)
   end
@@ -316,6 +320,7 @@ defmodule Registry do
   Similar to `start_link/1` except the required options,
   `keys` and `name` are given as arguments.
   """
+  @since "1.4.0"
   @spec start_link(keys, registry, keyword) :: {:ok, pid} | {:error, term}
   def start_link(keys, name, options \\ []) when keys in @keys and is_atom(name) do
     start_link([keys: keys, name: name] ++ options)
@@ -350,6 +355,7 @@ defmodule Registry do
       [{self(), 2}]
 
   """
+  @since "1.4.0"
   @spec update_value(registry, key, (value -> value)) ::
           {new_value :: term, old_value :: term} | :error
   def update_value(registry, key, callback) when is_atom(registry) and is_function(callback, 1) do
@@ -393,6 +399,7 @@ defmodule Registry do
   See the module documentation for examples of using the `dispatch/3`
   function for building custom dispatching or a pubsub system.
   """
+  @since "1.4.0"
   @spec dispatch(registry, key, (entries :: [{pid, value}] -> term), keyword) :: :ok
   def dispatch(registry, key, mfa_or_fun, opts \\ [])
       when is_atom(registry) and is_function(mfa_or_fun, 1)
@@ -506,6 +513,7 @@ defmodule Registry do
       [{self(), :another}, {self(), :world}]
 
   """
+  @since "1.4.0"
   @spec lookup(registry, key) :: [{pid, value}]
   def lookup(registry, key) when is_atom(registry) do
     case key_info!(registry) do
@@ -571,6 +579,7 @@ defmodule Registry do
       [{self(), {1, :atom, 1}}, {self(), {2, :atom, 2}}]
 
   """
+  @since "1.4.0"
   @spec match(registry, key, match_pattern :: term, guards :: list()) :: [{pid, term}]
   def match(registry, key, pattern, guards \\ []) when is_atom(registry) and is_list(guards) do
     guards = [{:"=:=", {:element, 1, :"$_"}, {:const, key}} | guards]
@@ -623,6 +632,7 @@ defmodule Registry do
       ["hello", "hello"]
 
   """
+  @since "1.4.0"
   @spec keys(registry, pid) :: [key]
   def keys(registry, pid) when is_atom(registry) and is_pid(pid) do
     {kind, partitions, _, pid_ets, _} = info!(registry)
@@ -695,6 +705,7 @@ defmodule Registry do
       []
 
   """
+  @since "1.4.0"
   @spec unregister(registry, key) :: :ok
   def unregister(registry, key) when is_atom(registry) do
     self = self()
@@ -847,6 +858,7 @@ defmodule Registry do
       ["hello", "hello"]
 
   """
+  @since "1.4.0"
   @spec register(registry, key, value) :: {:ok, pid} | {:error, {:already_registered, pid}}
   def register(registry, key, value) when is_atom(registry) do
     self = self()
@@ -919,6 +931,7 @@ defmodule Registry do
       :error
 
   """
+  @since "1.4.0"
   @spec meta(registry, meta_key) :: {:ok, meta_value} | :error
   def meta(registry, key) when is_atom(registry) and (is_atom(key) or is_tuple(key)) do
     try do
@@ -950,6 +963,7 @@ defmodule Registry do
       {:ok, "tuple_value"}
 
   """
+  @since "1.4.0"
   @spec put_meta(registry, meta_key, meta_value) :: :ok
   def put_meta(registry, key, value) when is_atom(registry) and (is_atom(key) or is_tuple(key)) do
     try do

lib/elixir/lib/stream.ex

@@ -578,6 +578,7 @@ defmodule Stream do
       [1, 2, 3, 4, 5]
 
   """
+  @since "1.4.0"
   @spec map_every(Enumerable.t(), non_neg_integer, (element -> any)) :: Enumerable.t()
   def map_every(enum, nth, fun)
 
@@ -1109,6 +1110,7 @@ defmodule Stream do
       [{1, :a, "foo"}, {2, :b, "bar"}, {3, :c, "baz"}]
 
   """
+  @since "1.4.0"
   @spec zip([Enumerable.t()]) :: Enumerable.t()
   @spec zip(Enumerable.t()) :: Enumerable.t()
   def zip(enumerables) do

lib/elixir/lib/task.ex

@@ -387,6 +387,7 @@ defmodule Task do
       Enum.to_list(stream)
 
   """
+  @since "1.4.0"
   @spec async_stream(Enumerable.t(), module, atom, [term], keyword) :: Enumerable.t()
   def async_stream(enumerable, module, function, args, options \\ [])
       when is_atom(module) and is_atom(function) and is_list(args) do
@@ -412,6 +413,7 @@ defmodule Task do
 
   See `async_stream/5` for discussion, options, and more examples.
   """
+  @since "1.4.0"
   @spec async_stream(Enumerable.t(), (term -> term), keyword) :: Enumerable.t()
   def async_stream(enumerable, fun, options \\ []) when is_function(fun, 1) do
     build_stream(enumerable, fun, options)

lib/elixir/lib/task/supervisor.ex

@@ -193,6 +193,7 @@ defmodule Task.Supervisor do
       Enum.to_list(stream)
 
   """
+  @since "1.4.0"
   @spec async_stream(Supervisor.supervisor(), Enumerable.t(), module, atom, [term], keyword) ::
           Enumerable.t()
   def async_stream(supervisor, enumerable, module, function, args, options \\ [])
@@ -210,6 +211,7 @@ defmodule Task.Supervisor do
 
   See `async_stream/6` for discussion, options, and examples.
   """
+  @since "1.4.0"
   @spec async_stream(Supervisor.supervisor(), Enumerable.t(), (term -> term), keyword) ::
           Enumerable.t()
   def async_stream(supervisor, enumerable, fun, options \\ []) when is_function(fun, 1) do
@@ -226,6 +228,7 @@ defmodule Task.Supervisor do
 
   See `async_stream/6` for discussion, options, and examples.
   """
+  @since "1.4.0"
   @spec async_stream_nolink(
           Supervisor.supervisor(),
           Enumerable.t(),
@@ -249,6 +252,7 @@ defmodule Task.Supervisor do
 
   See `async_stream/6` for discussion and examples.
   """
+  @since "1.4.0"
   @spec async_stream_nolink(Supervisor.supervisor(), Enumerable.t(), (term -> term), keyword) ::
           Enumerable.t()
   def async_stream_nolink(supervisor, enumerable, fun, options \\ []) when is_function(fun, 1) do

lib/iex/lib/iex/helpers.ex

@@ -1015,6 +1015,7 @@ defmodule IEx.Helpers do
       13
 
   """
+  @since "1.4.0"
   defmacro import_file(path) when is_binary(path) do
     import_file_if_available(path, false)
   end