Extend Duration shift documentation (#13640)

lib/elixir/lib/calendar/date.ex

@@ -764,8 +764,9 @@ defmodule Date do
 
   When using the default ISO calendar, durations are collapsed and
   applied in the order of months and then days:
-  - when shifting by 1 year and 2 months the date is actually shifted by 14 months
-  - when shifting by 2 weeks and 3 days the date is shifted by 17 days
+
+  * when shifting by 1 year and 2 months the date is actually shifted by 14 months
+  * when shifting by 2 weeks and 3 days the date is shifted by 17 days
 
   When shifting by month, days are rounded down to the nearest valid date.
 

lib/elixir/lib/calendar/datetime.ex

@@ -1708,8 +1708,9 @@ defmodule DateTime do
 
   When using the default ISO calendar, durations are collapsed and
   applied in the order of months, then seconds and microseconds:
-  - when shifting by 1 year and 2 months the date is actually shifted by 14 months
-  - weeks, days and smaller units are collapsed into seconds and microseconds
+
+  * when shifting by 1 year and 2 months the date is actually shifted by 14 months
+  * weeks, days and smaller units are collapsed into seconds and microseconds
 
   When shifting by month, days are rounded down to the nearest valid date.
 

lib/elixir/lib/calendar/duration.ex

@@ -26,7 +26,7 @@ defmodule Duration do
       iex> Date.shift(~D[2016-01-03], Duration.new!(month: 2))
       ~D[2016-03-03]
 
-  It is important to notice that shifting is not an arithmetic operation.
+  It is important to note that shifting is not an arithmetic operation.
   For example, adding `date + 1 month + 1 month` does not yield the same
   result as `date + 2 months`. Let's see an example:
 
@@ -46,9 +46,19 @@ defmodule Duration do
     * larger units (such as years and months) are applied before
       smaller ones (such as weeks, hours, days, and so on)
 
+    * units are collapsed into months (`:year` and `:month`),
+      seconds (`:week`, `:day`, `:hour`, `:minute`, `:second`)
+      and microseconds (`:microsecond`) before they are applied
+
+    * 1 year is equivalent to 12 months, 1 week is equivalent to 7 days.
+      Therefore, 4 weeks _are not_ equivalent to 1 month
+
     * in case of non-existing dates, the results are rounded down to the
       nearest valid date
 
+  As the `shift/2` functions are calendar aware, they are guaranteed to return
+  valid date/times, considering leap years as well as DST in applicable time zones.
+
   ## Intervals
 
   Durations in Elixir can be combined with stream operations to build intervals.

lib/elixir/lib/calendar/naive_datetime.ex

@@ -578,8 +578,9 @@ defmodule NaiveDateTime do
 
   When using the default ISO calendar, durations are collapsed and
   applied in the order of months, then seconds and microseconds:
-  - when shifting by 1 year and 2 months the date is actually shifted by 14 months
-  - weeks, days and smaller units are collapsed into seconds and microseconds
+
+  * when shifting by 1 year and 2 months the date is actually shifted by 14 months
+  * weeks, days and smaller units are collapsed into seconds and microseconds
 
   When shifting by month, days are rounded down to the nearest valid date.