Support adding arbitrary docs metadata with @doc keyword() (#7852)

Author: lackac

lib/elixir/lib/access.ex

@@ -774,7 +774,7 @@ defmodule Access do
       ** (RuntimeError) Access.filter/1 expected a list, got: %{}
 
   """
-  @since "1.6.0"
+  @doc since: "1.6.0"
   @spec filter((term -> boolean)) :: access_fun(data :: list, get_value :: list)
   def filter(func) when is_function(func) do
     fn op, data, next -> filter(op, data, func, next) end

lib/elixir/lib/agent.ex

@@ -144,7 +144,7 @@ defmodule Agent do
 
   See `Supervisor`.
   """
-  @since "1.5.0"
+  @doc since: "1.5.0"
   def child_spec(arg) do
     %{
       id: Agent,

lib/elixir/lib/calendar.ex

@@ -234,7 +234,7 @@ defmodule Calendar do
   between them. If they are compatible, this means that we can also convert
   dates as well as naive datetimes between them.
   """
-  @since "1.5.0"
+  @doc since: "1.5.0"
   @spec compatible_calendars?(Calendar.calendar(), Calendar.calendar()) :: boolean
   def compatible_calendars?(calendar, calendar), do: true
 
@@ -247,7 +247,7 @@ defmodule Calendar do
   Returns a microsecond tuple truncated to a given precision (`:microsecond`,
   `:millisecond` or `:second`).
   """
-  @since "1.6.0"
+  @doc since: "1.6.0"
   @spec truncate(Calendar.microsecond(), :microsecond | :millisecond | :second) ::
           Calendar.microsecond()
   def truncate(microsecond_tuple, :microsecond), do: microsecond_tuple

lib/elixir/lib/calendar/date.ex

@@ -87,8 +87,7 @@ defmodule Date do
       -366
 
   """
-
-  @since "1.5.0"
+  @doc since: "1.5.0"
   @spec range(Date.t(), Date.t()) :: Date.Range.t()
   def range(%Date{calendar: calendar} = first, %Date{calendar: calendar} = last) do
     {first_days, _} = to_iso_days(first)
@@ -116,7 +115,7 @@ defmodule Date do
       true
 
   """
-  @since "1.4.0"
+  @doc since: "1.4.0"
   @spec utc_today(Calendar.calendar()) :: t
   def utc_today(calendar \\ Calendar.ISO)
 
@@ -148,7 +147,7 @@ defmodule Date do
       true
 
   """
-  @since "1.4.0"
+  @doc since: "1.4.0"
   @spec leap_year?(Calendar.date()) :: boolean()
   def leap_year?(date)
 
@@ -169,7 +168,7 @@ defmodule Date do
       29
 
   """
-  @since "1.4.0"
+  @doc since: "1.4.0"
   @spec days_in_month(Calendar.date()) :: Calendar.day()
   def days_in_month(date)
 
@@ -186,7 +185,7 @@ defmodule Date do
       12
 
   """
-  @since "1.7.0"
+  @doc since: "1.7.0"
   @spec months_in_year(Calendar.date()) :: Calendar.month()
   def months_in_year(date)
 
@@ -436,7 +435,7 @@ defmodule Date do
       :eq
 
   """
-  @since "1.4.0"
+  @doc 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
@@ -484,7 +483,7 @@ defmodule Date do
       {:ok, %Date{calendar: Calendar.Holocene, year: 12000, month: 1, day: 1}}
 
   """
-  @since "1.5.0"
+  @doc since: "1.5.0"
   @spec convert(Calendar.date(), Calendar.calendar()) ::
           {:ok, t} | {:error, :incompatible_calendars}
   def convert(%{calendar: calendar, year: year, month: month, day: day}, calendar) do
@@ -518,7 +517,7 @@ defmodule Date do
       %Date{calendar: Calendar.Holocene, year: 12000, month: 1, day: 1}
 
   """
-  @since "1.5.0"
+  @doc since: "1.5.0"
   @spec convert!(Calendar.date(), Calendar.calendar()) :: t
   def convert!(date, calendar) do
     case convert(date, calendar) do
@@ -550,7 +549,7 @@ defmodule Date do
       ~D[-0011-12-30]
 
   """
-  @since "1.5.0"
+  @doc since: "1.5.0"
   @spec add(Calendar.date(), integer()) :: t
   def add(%{calendar: calendar} = date, days) do
     {iso_days, fraction} = to_iso_days(date)
@@ -576,7 +575,7 @@ defmodule Date do
       -2
 
   """
-  @since "1.5.0"
+  @doc since: "1.5.0"
   @spec diff(Calendar.date(), Calendar.date()) :: integer
   def diff(%{calendar: Calendar.ISO} = date1, %{calendar: Calendar.ISO} = date2) do
     %{year: year1, month: month1, day: day1} = date1
@@ -634,7 +633,7 @@ defmodule Date do
       3
 
   """
-  @since "1.4.0"
+  @doc 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,7 +186,7 @@ defmodule DateTime do
       #DateTime<2016-05-24 13:26:08.003Z>
 
   """
-  @since "1.4.0"
+  @doc since: "1.4.0"
   @spec from_naive(NaiveDateTime.t(), Calendar.time_zone()) :: {:ok, t}
   def from_naive(naive_datetime, time_zone)
 
@@ -232,7 +232,7 @@ defmodule DateTime do
       #DateTime<2016-05-24 13:26:08.003Z>
 
   """
-  @since "1.4.0"
+  @doc 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
@@ -502,7 +502,7 @@ defmodule DateTime do
       {:error, :invalid_format}
 
   """
-  @since "1.4.0"
+  @doc 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
@@ -634,7 +634,7 @@ defmodule DateTime do
       :gt
 
   """
-  @since "1.4.0"
+  @doc 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,
@@ -685,7 +685,7 @@ defmodule DateTime do
       -18000
 
   """
-  @since "1.5.0"
+  @doc since: "1.5.0"
   @spec diff(Calendar.datetime(), Calendar.datetime()) :: integer()
   def diff(
         %{utc_offset: utc_offset1, std_offset: std_offset1} = datetime1,
@@ -725,7 +725,7 @@ defmodule DateTime do
       #DateTime<2017-11-07 11:45:18+01:00 CET Europe/Paris>
 
   """
-  @since "1.6.0"
+  @doc since: "1.6.0"
   @spec truncate(t(), :microsecond | :millisecond | :second) :: t()
   def truncate(%DateTime{microsecond: microsecond} = datetime, precision) do
     %{datetime | microsecond: Calendar.truncate(microsecond, precision)}
@@ -754,7 +754,7 @@ defmodule DateTime do
                       zone_abbr: "AMT"}}
 
   """
-  @since "1.5.0"
+  @doc since: "1.5.0"
   @spec convert(Calendar.datetime(), Calendar.calendar()) ::
           {:ok, t} | {:error, :incompatible_calendars}
 
@@ -829,7 +829,7 @@ defmodule DateTime do
                 zone_abbr: "AMT"}
 
   """
-  @since "1.5.0"
+  @doc since: "1.5.0"
   @spec convert!(Calendar.datetime(), Calendar.calendar()) :: t | no_return
   def convert!(datetime, calendar) do
     case convert(datetime, calendar) do

lib/elixir/lib/calendar/iso.ex

@@ -51,8 +51,8 @@ defmodule Calendar.ISO do
       {-365, {0, 86400000000}}
 
   """
+  @doc since: "1.5.0"
   @impl true
-  @since "1.5.0"
   @spec naive_datetime_to_iso_days(
           Calendar.year(),
           Calendar.month(),
@@ -81,6 +81,7 @@ defmodule Calendar.ISO do
       {-1, 1, 1, 0, 0, 0, {0, 6}}
 
   """
+  @doc since: "1.5.0"
   @spec naive_datetime_from_iso_days(Calendar.iso_days()) :: {
           Calendar.year(),
           Calendar.month(),
@@ -91,7 +92,6 @@ defmodule Calendar.ISO do
           Calendar.microsecond()
         }
   @impl true
-  @since "1.5.0"
   def naive_datetime_from_iso_days({days, day_fraction}) do
     {year, month, day} = date_from_iso_days(days)
     {hour, minute, second, microsecond} = time_from_day_fraction(day_fraction)
@@ -109,8 +109,8 @@ defmodule Calendar.ISO do
       {45296000123, 86400000000}
 
   """
+  @doc since: "1.5.0"
   @impl true
-  @since "1.5.0"
   @spec time_to_day_fraction(
           Calendar.hour(),
           Calendar.minute(),
@@ -137,8 +137,8 @@ defmodule Calendar.ISO do
       {13, 0, 0, {0, 6}}
 
   """
+  @doc since: "1.5.0"
   @impl true
-  @since "1.5.0"
   @spec time_from_day_fraction(Calendar.day_fraction()) ::
           {Calendar.hour(), Calendar.minute(), Calendar.second(), Calendar.microsecond()}
   def time_from_day_fraction({parts_in_day, parts_per_day}) do
@@ -156,7 +156,7 @@ defmodule Calendar.ISO do
 
   # Converts year, month, day to count of days since 0000-01-01.
   @doc false
-  @since "1.5.0"
+  @doc since: "1.5.0"
   def date_to_iso_days(0, 1, 1) do
     0
   end
@@ -174,7 +174,7 @@ defmodule Calendar.ISO do
 
   # Converts count of days since 0000-01-01 to {year, month, day} tuple.
   @doc false
-  @since "1.5.0"
+  @doc since: "1.5.0"
   def date_from_iso_days(days) when days in 0..3_652_424 do
     {year, day_of_year} = days_to_year(days)
     extra_day = if leap_year?(year), do: 1, else: 0
@@ -243,8 +243,8 @@ defmodule Calendar.ISO do
       12
 
   """
+  @doc since: "1.7.0"
   @impl true
-  @since "1.7.0"
   @spec months_in_year(year) :: 12
   def months_in_year(_year) do
     @months_in_year
@@ -462,8 +462,8 @@ defmodule Calendar.ISO do
     false
 
   """
+  @doc since: "1.5.0"
   @impl true
-  @since "1.5.0"
   @spec valid_date?(year, month, day) :: boolean
   def valid_date?(year, month, day) do
     month in 1..12 and year in -9999..9999 and day in 1..days_in_month(year, month)
@@ -484,8 +484,8 @@ defmodule Calendar.ISO do
     false
 
   """
+  @doc since: "1.5.0"
   @impl true
-  @since "1.5.0"
   @spec valid_time?(Calendar.hour(), Calendar.minute(), Calendar.secon(), Calendar.microsecond()) ::
           boolean
   def valid_time?(hour, minute, second, {microsecond, precision}) do
@@ -496,8 +496,8 @@ defmodule Calendar.ISO do
   @doc """
   See `c:Calendar.day_rollover_relative_to_midlight_utc/0` for documentation.
   """
+  @doc since: "1.5.0"
   @impl true
-  @since "1.5.0"
   @spec day_rollover_relative_to_midnight_utc() :: {0, 1}
   def day_rollover_relative_to_midnight_utc() do
     {0, 1}
@@ -566,7 +566,7 @@ defmodule Calendar.ISO do
     do: precision_for_unit(div(number, 10), precision + 1)
 
   @doc false
-  @since "1.5.0"
+  @doc since: "1.5.0"
   def date_to_iso8601(year, month, day, format \\ :extended) do
     date_to_string(year, month, day, format)
   end
@@ -671,15 +671,15 @@ defmodule Calendar.ISO do
   end
 
   @doc false
-  @since "1.5.0"
+  @doc since: "1.5.0"
   def iso_days_to_unit({days, {parts, ppd}}, unit) do
     day_microseconds = days * @parts_per_day
     microseconds = div(parts * @parts_per_day, ppd)
     System.convert_time_unit(day_microseconds + microseconds, :microsecond, unit)
   end
 
   @doc false
-  @since "1.5.0"
+  @doc since: "1.5.0"
   def add_day_fraction_to_iso_days({days, {parts, ppd}}, add, ppd) do
     normalize_iso_days(days, parts + add, ppd)
   end