Github user DaveBirdsall commented on a diff in the pull request:
https://github.com/apache/incubator-trafodion/pull/1309#discussion_r152650488
--- Diff:
docs/sql_reference/src/asciidoc/_chapters/sql_functions_and_expressions.adoc ---
@@ -2325,82 +2328,206 @@ following abbreviations:
* `startdate`
+
-may be of type DATE or TIMESTAMP.
+may be of type DATE or TIMESTAMP, should be enclosed in quotation marks.
See <<datetime_value_expressions,Datetime Value Expressions>>.
* `enddate`
+
-may be of type DATE or TIMESTAMP.
+may be of type DATE or TIMESTAMP, should be enclosed in quotation marks.
See <<datetime_value_expressions,Datetime Value Expressions>>.
-The method of counting crossed boundaries such as days, minutes, and
-seconds makes the result given by DATEDIFF consistent across all data
-types. The result is a signed integer value equal to the number of
-datepart boundaries crossed between the first and second date.
-
-For example, the number of weeks between Sunday, January 4, and Sunday,
-January 1 , is 1. The number of months between March 31 and April 1
-would be 1 because the month boundary is crossed from March to April.
-The DATEDIFF function generates an error if the result is out of range
-for integer values. For seconds, the maximum number is equivalent to
-approximately 68 years. The DATEDIFF function generates an error if a
-difference in weeks is requested and one of the two dates precedes
-January 7 of the year 0001.
+[[considerations_for_datediff]]
+=== Considerations for DATEDIFF
+
+[[boundary]]
+==== Boundary
+
+The method of counting crossed boundaries such as days, minutes, and
seconds makes the result given by DATEDIFF consistent across all data types.
+
+The result is a signed integer value equal to the number of _datepart_
boundaries crossed between _startdate_ and _enddate_, because the DATEDIFF
function does not calculate the full _datepart_, it counts the difference
between _startdate_ and _enddate_.
+
+For example:
+
+* The difference between 2017-12-31 23:59:59 and 2018-01-01 00:00:00 is
only a single second.
+
++
+However, the DATEDIFF difference is 1 minute, 1 hour, 1 day, 0 week^1^, 1
month, 1 quarter or 1 month depending on the specified _datepart_.
+
++
+^1^ NOTE: 2017-12-31 (_startdate_) falls on Sunday which cannot be
counted. For more information, see <<the_first_day_of_week,The first day of
week>>.
+
+* Likewise, the difference between 2017-01-01 and 2018-12-31 is almost two
years.
+
++
+However, the DATEDIFF difference is 1 year if the specified _datepart_ is
YEAR.
+
+[[the_first_day_of_week]]
+==== The first day of week
+
+* This value cannot be specified, the default value is Sunday.
--- End diff --
Possible wordsmith: "The first day of the week is Sunday. Changing the
first day of the week is not supported."
---
