more docs

distribution/lib/Standard/Base/0.0.0-dev/src/Data/Time/Date.enso

@@ -317,6 +317,21 @@ type Date
        For the purpose of this method, the business days are defined to be
        Monday through Friday.
 
+       This method always returns a day which is a business day - if the shift
+       amount is zero, the closest following business day is returned. For the
+       purpose of calculating the shift, the holidays are treated as if we were
+       starting at the next business day after them, for example counting the
+       shift starting on Saturday or Sunday works as if we were counting the
+       shift from Monday (for positive shifts). So shifting Sunday by zero days
+       will return Monday, but shifting it by one day will return a Tuesday
+       (so that there is the full work day - Monday) within the interval. For
+       negative shifts, shifting either Saturday or Sunday one day backwards
+       will return Friday, but shifting Monday one day backwards will return a
+       Friday. The whole logic is made consistent with `work_days_until`, so
+       that the following properties hold:
+           date.work_days_until (date.add_work_days N) == N for any N >= 0
+           (date.add_work_days N).work_days_until date == -N for any N < 0
+
        Arguments:
        - amount: The number of business days to shift the date by. If `amount`
          is zero, the current date is returned, unless it is a weekend or a

distribution/lib/Standard/Base/0.0.0-dev/src/Data/Time/Date_Time.enso

@@ -397,8 +397,22 @@ type Date_Time
        For the purpose of this method, the business days are defined to be
        Monday through Friday.
 
-       The time of day is preserved, only the date is shifted. If the time of
-       day is not valid for the new date (DST gaps), TODO
+       This method always returns a day which is a business day - if the shift
+       amount is zero, the closest following business day is returned. For the
+       purpose of calculating the shift, the holidays are treated as if we were
+       starting at the next business day after them, for example counting the
+       shift starting on Saturday or Sunday works as if we were counting the
+       shift from Monday (for positive shifts). So shifting Sunday by zero days
+       will return Monday, but shifting it by one day will return a Tuesday
+       (so that there is the full work day - Monday) within the interval. For
+       negative shifts, shifting either Saturday or Sunday one day backwards
+       will return Friday, but shifting Monday one day backwards will return a
+       Friday. The whole logic is made consistent with `work_days_until`, so
+       that the following properties hold:
+           date.work_days_until (date.add_work_days N) == N for any N >= 0
+           (date.add_work_days N).work_days_until date == -N for any N < 0
+
+       The time of day is preserved, only the date is shifted.
 
        Arguments:
        - amount: The number of business days to shift the date by. If `amount`