Documentation for time:plus for dates

[SFRailsback]

I think the documentation needs to say these things explicitly about time:plus on logotimes of type date:

When the value added is of time units less than 1 day (e.g., hour, second), then the number of days added is rounded down to the next lowest integer, even if that number is negative. So adding 47 hours increases the date by 1 day, while adding -47 hours decreases the date by 2 days. Adding 1 hour produces no change in date, but adding -1 hour decreases it by 1 day.

When the value added is a real number of days (e.g., 1.327 "DAY") this number is rounded down to the next integer, even if the number is negative. So adding -1.327 days reduces the date by 2 days.

When the value added is a month, then only the month (and possibly year) is changed; the day remains unchanged. If the number of months added is a real number, it is rounded to the next lowest integer, even if negative. Adding -2.3 months to 12/25/2015 results in 09/25/2015.

When the value added is in year units, then only the year changes and the month and day are unchanged. If the number of years added is a real number, it is rounded to the next lowest integer, even if negative. Adding -4.5 years to 12/25/2015 results in 12/25/2010.

When the value added is of time period type "DAYOFYEAR" it is treated as if of type "DAY", so the result can be in a different year. For example, time:plus (time:create "2000-12-30") 30 "DAYOFYEAR" reports a value of 2001-01-29.

[charlesres]

@SFRailsback Thanks for submitting an issue and feedback on the time:plus primitive. Rounding with dates is definitely tricky, especially when values truncate and round depending on the initial format. Adding some documentation on how rounding behaves, along with some details about converting and calculating values, would be helpful. I'll start off with the above and add some details for intuition.