doc: interval spill method for units greater than months

bmomjian · bmomjian · commit 1dd84002060c · 2021-08-03T12:17:58.000-04:00
Units are _truncated_ to months, but only in back branches since the recent commit. Reported-by: Bryn Llewellyn Discussion: https://postgr.es/m/BDAE4B56-3337-45A2-AC8A-30593849D6C0@yugabyte.com Backpatch-through: 9.6 to 14
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
@@ -2756,15 +2756,18 @@ P <optional> <replaceable>years</replaceable>-<replaceable>months</replaceable>-
     </para>
 
     <para>
-     In the verbose input format, and in some fields of the more compact
-     input formats, field values can have fractional parts; for example
-     <literal>'1.5 week'</literal> or <literal>'01:02:03.45'</literal>.  Such input is
-     converted to the appropriate number of months, days, and seconds
-     for storage.  When this would result in a fractional number of
-     months or days, the fraction is added to the lower-order fields
-     using the conversion factors 1 month = 30 days and 1 day = 24 hours.
-     For example, <literal>'1.5 month'</literal> becomes 1 month and 15 days.
-     Only seconds will ever be shown as fractional on output.
+     Field values can have fractional parts:  for example, <literal>'1.5
+     weeks'</literal> or <literal>'01:02:03.45'</literal>.  However,
+     because interval internally stores only three integer units (months,
+     days, microseconds), fractional units must be spilled to smaller
+     units.  Fractional parts of units greater than months is truncated to
+     be an integer number of months, e.g. <literal>'1.5 years'</literal>
+     becomes <literal>'1 year 6 mons'</literal>.  Fractional parts of
+     weeks and days are computed to be an integer number of days and
+     microseconds, assuming 30 days per month and 24 hours per day, e.g.,
+     <literal>'1.75 months'</literal> becomes <literal>1 mon 22 days
+     12:00:00</literal>.  Only seconds will ever be shown as fractional
+     on output.
     </para>
 
     <para>
@@ -2808,10 +2811,10 @@ P <optional> <replaceable>years</replaceable>-<replaceable>months</replaceable>-
 
     <para>
      Internally <type>interval</type> values are stored as months, days,
-     and seconds. This is done because the number of days in a month
+     and microseconds. This is done because the number of days in a month
      varies, and a day can have 23 or 25 hours if a daylight savings
      time adjustment is involved.  The months and days fields are integers
-     while the seconds field can store fractions.  Because intervals are
+     while the microseconds field can store fractional seconds.  Because intervals are
      usually created from constant strings or <type>timestamp</type> subtraction,
      this storage method works well in most cases, but can cause unexpected
      results:
