Update docs & typespecs for calendar modules (#6313)

Author: wojtekmach

lib/elixir/lib/calendar/date.ex

@@ -67,8 +67,11 @@ defmodule Date do
 
   ## Examples
 
-      iex> Date.range(~D[2000-01-01], ~D[2001-01-01])
-      #DateRange<~D[2000-01-01], ~D[2001-01-01]>
+      iex> Date.range(~D[1999-01-01], ~D[2000-01-01])
+      #DateRange<~D[1999-01-01], ~D[2000-01-01]>
+
+      iex> Date.range(~N[2000-01-01 09:00:00], ~D[1999-01-01])
+      #DateRange<~N[2000-01-01 09:00:00], ~D[1999-01-01]>
 
   A range of dates implements the `Enumerable` protocol, which means
   functions in the `Enum` module can be used to work with
@@ -83,7 +86,7 @@ defmodule Date do
       -366
   """
 
-  @spec range(Date.t, Date.t) :: Date.Range.t
+  @spec range(Calendar.date, Calendar.date) :: Date.Range.t
   def range(%{calendar: calendar} = first, %{calendar: calendar} = last) do
     {first_days, _} = to_rata_die(first)
     {last_days, _} = to_rata_die(last)
@@ -96,7 +99,8 @@ defmodule Date do
     }
   end
 
-  def range(%Date{}, %Date{}) do
+  def range(%{calendar: _, year: _, month: _, day: _},
+            %{calendar: _, year: _, month: _, day: _}) do
     raise ArgumentError, "both dates must have matching calendars"
   end
 
@@ -125,7 +129,7 @@ defmodule Date do
   end
 
   @doc """
-  Returns true if the year in `date` is a leap year.
+  Returns true if the year in the given `date` is a leap year.
 
   ## Examples
 
@@ -149,7 +153,7 @@ defmodule Date do
   end
 
   @doc """
-  Returns the number of days in the given date month.
+  Returns the number of days in the given `date` month.
 
   ## Examples
 
@@ -309,7 +313,7 @@ defmodule Date do
   end
 
   @doc """
-  Converts a `Date` struct to an Erlang date tuple.
+  Converts the given `date` to an Erlang date tuple.
 
   Only supports converting dates which are in the ISO calendar,
   or other calendars in which the days also start at midnight.
@@ -375,7 +379,7 @@ defmodule Date do
   end
 
   @doc """
-  Compares two `Date` structs.
+  Compares two date structs.
 
   Returns `:gt` if first date is later than the second
   and `:lt` for vice versa. If the two dates are equal
@@ -424,15 +428,25 @@ defmodule Date do
   end
 
   @doc """
-  Converts a date from one calendar to another.
+  Converts the given `date` from it's calendar to the given `calendar`.
 
   Returns `{:ok, date}` if the calendars are compatible,
   or `{:error, :incompatible_calendars}` if they are not.
 
   See also `Calendar.compatible_calendars?/2`.
+
+  ## Examples
+
+  Imagine someone implements `Calendar.Julian`:
+
+      iex> Date.convert(~D[2000-01-01], Calendar.Julian)
+      {:ok, %Date{calendar: Calendar.Julian, year: 1999, month: 12, day: 19}}
+
   """
-  @spec convert(Calendar.date(), Calendar.calendar) :: {:ok, Date.t} | {:error, :incompatible_calendars}
-  def convert(%Date{calendar: calendar} = date, calendar), do: {:ok, date}
+  @spec convert(Calendar.date, Calendar.calendar) :: {:ok, t} | {:error, :incompatible_calendars}
+  def convert(%{calendar: calendar, year: year, month: month, day: day}, calendar) do
+    {:ok, %Date{calendar: calendar, year: year, month: month, day: day}}
+  end
   def convert(%{calendar: calendar} = date, target_calendar) do
     if Calendar.compatible_calendars?(calendar, target_calendar) do
       result_date =
@@ -448,8 +462,16 @@ defmodule Date do
   @doc """
   Similar to `Date.convert/2`, but raises an `ArgumentError`
   if the conversion between the two calendars is not possible.
+
+  ## Examples
+
+  Imagine someone implements `Calendar.Julian`:
+
+      iex> Date.convert!(~D[2000-01-01], Calendar.Julian)
+      %Date{calendar: Calendar.Julian, year: 1999, month: 12, day: 19}
+
   """
-  @spec convert!(Date.t, Calendar.calendar) :: Date.t
+  @spec convert!(Calendar.date, Calendar.calendar) :: t
   def convert!(date, calendar) do
     case convert(date, calendar) do
       {:ok, value} ->
@@ -460,7 +482,7 @@ defmodule Date do
   end
 
   @doc """
-  Adds the number of days to the given date.
+  Adds the number of days to the given `date`.
 
   The days are counted as gregorian days. The date is returned in the same
   calendar as it was given in.
@@ -472,9 +494,12 @@ defmodule Date do
       iex> Date.add(~D[2000-01-01], 2)
       ~D[2000-01-03]
 
+      iex> Date.add(~N[2000-01-01 09:00:00], 2)
+      ~D[2000-01-03]
+
   """
-  @spec add(Date.t, integer()) :: Date.t
-  def add(%Date{calendar: calendar} = date, days) do
+  @spec add(Calendar.date, integer()) :: t
+  def add(%{calendar: calendar} = date, days) do
     {rata_days, fraction} = to_rata_die(date)
     from_rata_die({rata_days + days, fraction}, calendar)
   end
@@ -493,16 +518,19 @@ defmodule Date do
       iex> Date.diff(~D[2000-01-01], ~D[2000-01-03])
       -2
 
+      iex> Date.diff(~D[2000-01-01], ~N[2000-01-03 09:00:00])
+      -2
+
   """
-  @spec diff(Date.t, Date.t) :: integer
-  def diff(%Date{calendar: Calendar.ISO, year: year1, month: month1, day: day1},
-           %Date{calendar: Calendar.ISO, year: year2, month: month2, day: day2}) do
+  @spec diff(Calendar.date, Calendar.date) :: integer
+  def diff(%{calendar: Calendar.ISO, year: year1, month: month1, day: day1},
+           %{calendar: Calendar.ISO, year: year2, month: month2, day: day2}) do
     Calendar.ISO.date_to_rata_die_days(year1, month1, day1) -
       Calendar.ISO.date_to_rata_die_days(year2, month2, day2)
   end
 
-  def diff(%Date{} = date1, %Date{} = date2) do
-    if Calendar.compatible_calendars?(date1.calendar, date2.calendar) do
+  def diff(%{calendar: calendar1} = date1, %{calendar: calendar2} = date2) do
+    if Calendar.compatible_calendars?(calendar1, calendar2) do
       {days1, _} = to_rata_die(date1)
       {days2, _} = to_rata_die(date2)
       days1 - days2
@@ -528,7 +556,7 @@ defmodule Date do
   end
 
   @doc """
-  Calculates the day of the week of a given `Date` struct.
+  Calculates the day of the week of a given `date`.
 
   Returns the day of the week as an integer. For the ISO 8601
   calendar (the default), it is an integer from 1 to 7, where

lib/elixir/lib/calendar/datetime.ex

@@ -12,6 +12,11 @@ defmodule DateTime do
   are structural and based on the DateTime struct fields. For proper
   comparison between datetimes, use the `compare/2` function.
 
+  The functions on this module work with the `DateTime` struct as well
+  as any struct that contains the same fields as the `DateTime` struct.
+  Such functions expect `t:Calendar.datetime/0` in their typespecs
+  (instead of `t:t/0`).
+
   Developers should avoid creating the DateTime struct directly
   and instead rely on the functions provided by this module as
   well as the ones in 3rd party calendar libraries.
@@ -52,13 +57,13 @@ defmodule DateTime do
       "Etc/UTC"
 
   """
-  @spec utc_now(Calendar.calendar) :: DateTime.t
+  @spec utc_now(Calendar.calendar) :: t
   def utc_now(calendar \\ Calendar.ISO) do
     System.os_time |> from_unix!(:native, calendar)
   end
 
   @doc """
-  Converts the given Unix time to DateTime.
+  Converts the given Unix time to `DateTime`.
 
   The integer can be given in different unit
   according to `System.convert_time_unit/3` and it will
@@ -86,7 +91,7 @@ defmodule DateTime do
   Negative Unix times are supported, up to -62167219200 seconds,
   which is equivalent to "0000-01-01T00:00:00Z" or 0 Gregorian seconds.
   """
-  @spec from_unix(integer, :native | System.time_unit, Calendar.calendar) :: {:ok, DateTime.t} | {:error, atom}
+  @spec from_unix(integer, :native | System.time_unit, Calendar.calendar) :: {:ok, t} | {:error, atom}
   def from_unix(integer, unit \\ :second, calendar \\ Calendar.ISO) when is_integer(integer) do
     case Calendar.ISO.from_unix(integer, unit) do
       {:ok, {year, month, day}, {hour, minute, second}, microsecond} ->
@@ -100,7 +105,7 @@ defmodule DateTime do
   end
 
   @doc """
-  Converts the given Unix time to DateTime.
+  Converts the given Unix time to `DateTime`.
 
   The integer can be given in different unit
   according to `System.convert_time_unit/3` and it will
@@ -122,7 +127,7 @@ defmodule DateTime do
       #DateTime<2015-05-25 13:26:08.868569Z>
 
   """
-  @spec from_unix!(integer, :native | System.time_unit, Calendar.calendar) :: DateTime.t
+  @spec from_unix!(integer, :native | System.time_unit, Calendar.calendar) :: t
   def from_unix!(integer, unit \\ :second, calendar \\ Calendar.ISO) when is_atom(unit) do
     case from_unix(integer, unit, calendar) do
       {:ok, datetime} ->
@@ -133,7 +138,7 @@ defmodule DateTime do
   end
 
   @doc """
-  Converts the given NaiveDateTime to DateTime.
+  Converts the given `NaiveDateTime` to `DateTime`.
 
   It expects a time zone to put the NaiveDateTime in.
   Currently it only supports "Etc/UTC" as time zone.
@@ -145,7 +150,7 @@ defmodule DateTime do
       #DateTime<2016-05-24 13:26:08.003Z>
 
   """
-  @spec from_naive(NaiveDateTime.t, Calendar.time_zone) :: {:ok, DateTime.t}
+  @spec from_naive(NaiveDateTime.t, Calendar.time_zone) :: {:ok, t}
   def from_naive(naive_datetime, time_zone)
 
   def from_naive(%NaiveDateTime{calendar: calendar,
@@ -157,7 +162,7 @@ defmodule DateTime do
   end
 
   @doc """
-  Converts the given NaiveDateTime to DateTime.
+  Converts the given `NaiveDateTime` to `DateTime`.
 
   It expects a time zone to put the NaiveDateTime in.
   Currently it only supports "Etc/UTC" as time zone.
@@ -168,7 +173,7 @@ defmodule DateTime do
       #DateTime<2016-05-24 13:26:08.003Z>
 
   """
-  @spec from_naive!(non_neg_integer, :native | System.time_unit) :: DateTime.t
+  @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
       {:ok, datetime} ->
@@ -179,9 +184,9 @@ defmodule DateTime do
   end
 
   @doc """
-  Converts the given DateTime to Unix time.
+  Converts the given `datetime` to Unix time.
 
-  The DateTime is expected to be using the ISO calendar
+  The `datetime` is expected to be using the ISO calendar
   with a year greater than or equal to 0.
 
   It will return the integer with the given unit,
@@ -205,18 +210,18 @@ defmodule DateTime do
       -17412508655
 
   """
-  @spec to_unix(DateTime.t, System.time_unit) :: non_neg_integer
+  @spec to_unix(Calendar.datetime, System.time_unit) :: integer
   def to_unix(datetime, unit \\ :second)
 
-  def to_unix(%DateTime{utc_offset: utc_offset, std_offset: std_offset} = datetime, unit) do
+  def to_unix(%{utc_offset: utc_offset, std_offset: std_offset} = datetime, unit) do
     {days, fraction} = to_rata_die(datetime)
     unix_units = Calendar.ISO.rata_die_to_unit({days - @unix_days, fraction}, unit)
     offset_units = System.convert_time_unit(utc_offset + std_offset, :second, unit)
     unix_units - offset_units
   end
 
   @doc """
-  Converts a `DateTime` into a `NaiveDateTime`.
+  Converts the given `datetime` into a `NaiveDateTime`.
 
   Because `NaiveDateTime` does not hold time zone information,
   any time zone related data will be lost during the conversion.
@@ -230,7 +235,8 @@ defmodule DateTime do
       ~N[2000-02-29 23:00:07.0]
 
   """
-  def to_naive(%DateTime{year: year, month: month, day: day, calendar: calendar,
+  @spec to_naive(t) :: NaiveDateTime.t
+  def to_naive(%DateTime{calendar: calendar, year: year, month: month, day: day,
                          hour: hour, minute: minute, second: second, microsecond: microsecond}) do
     %NaiveDateTime{year: year, month: month, day: day, calendar: calendar,
                    hour: hour, minute: minute, second: second, microsecond: microsecond}
@@ -251,6 +257,7 @@ defmodule DateTime do
       ~D[2000-02-29]
 
   """
+  @spec to_date(t) :: Date.t
   def to_date(%DateTime{year: year, month: month, day: day, calendar: calendar}) do
     %Date{year: year, month: month, day: day, calendar: calendar}
   end
@@ -270,6 +277,7 @@ defmodule DateTime do
       ~T[23:00:07.0]
 
   """
+  @spec to_time(t) :: Time.t
   def to_time(%DateTime{hour: hour, minute: minute, second: second, microsecond: microsecond, calendar: calendar}) do
     %Time{hour: hour, minute: minute, second: second, microsecond: microsecond, calendar: calendar}
   end
@@ -429,7 +437,7 @@ defmodule DateTime do
   end
 
   @doc """
-  Converts the given datetime to a string according to its calendar.
+  Converts the given `datetime` to a string according to its calendar.
 
   ### Examples
 
@@ -485,7 +493,7 @@ defmodule DateTime do
   end
 
   @doc """
-  Compares two `DateTime` structs.
+  Compares two datetime structs.
 
   Returns `:gt` if first datetime is later than the second
   and `:lt` for vice versa. If the two datetimes are equal
@@ -506,7 +514,7 @@ defmodule DateTime do
       :gt
 
   """
-  @spec compare(DateTime.t, DateTime.t) :: :lt | :eq | :gt
+  @spec compare(Calendar.datetime, Calendar.datetime) :: :lt | :eq | :gt
   def compare(%DateTime{utc_offset: utc_offset1, std_offset: std_offset1} = datetime1,
               %DateTime{utc_offset: utc_offset2, std_offset: std_offset2} = datetime2) do
     {days1, {parts1, ppd1}} =
@@ -552,9 +560,9 @@ defmodule DateTime do
       -18000
 
   """
-  @spec diff(DateTime.t, DateTime.t) :: integer()
-  def diff(%DateTime{utc_offset: utc_offset1, std_offset: std_offset1} = datetime1,
-           %DateTime{utc_offset: utc_offset2, std_offset: std_offset2} = datetime2, unit \\ :second) do
+  @spec diff(Calendar.datetime, Calendar.datetime) :: integer()
+  def diff(%{utc_offset: utc_offset1, std_offset: std_offset1} = datetime1,
+           %{utc_offset: utc_offset2, std_offset: std_offset2} = datetime2, unit \\ :second) do
     naive_diff =
       (datetime1 |> to_rata_die() |> Calendar.ISO.rata_die_to_unit(unit)) -
       (datetime2 |> to_rata_die() |> Calendar.ISO.rata_die_to_unit(unit))
@@ -585,8 +593,12 @@ defmodule DateTime do
 
   """
   @spec convert(Calendar.datetime, Calendar.calendar) :: {:ok, t} | {:error, :incompatible_calendars}
-  def convert(%DateTime{calendar: calendar} = datetime, calendar) do
-    {:ok, datetime}
+  def convert(%{calendar: calendar, year: year, month: month, day: day,
+                hour: hour, minute: minute, second: second, microsecond: microsecond,
+                time_zone: time_zone, zone_abbr: zone_abbr, utc_offset: utc_offset, std_offset: std_offset}, calendar) do
+    {:ok, %DateTime{calendar: calendar, year: year, month: month, day: day,
+                    hour: hour, minute: minute, second: second, microsecond: microsecond,
+                    time_zone: time_zone, zone_abbr: zone_abbr, utc_offset: utc_offset, std_offset: std_offset}}
   end
 
   def convert(%{calendar: dt_calendar, microsecond: {_, precision}} = datetime, calendar) do