Add comments regarding 31 days per month by default

Author: MaxGekk

sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/util/IntervalUtils.scala

@@ -127,7 +127,11 @@ object IntervalUtils {
    *
    * @param cal - the interval to get duration
    * @param targetUnit - time units of the result
-   * @param daysPerMonth - the number of days per one month
+   * @param daysPerMonth - the number of days per one month. The default value is 31 days
+   *                       per month. This value was taken as the default because it is used
+   *                       in Structured Streaming for watermark calculations. Having 31 days
+   *                       per month, we can guarantee that events are not dropped before
+   *                       the end of any month (February with 29 days or January with 31 days).
    * @return duration in the specified time units
    */
   def getDuration(
@@ -142,8 +146,12 @@ object IntervalUtils {
   /**
    * Checks the interval is negative
    *
-   * @param cal - the checked interval
-   * @param daysPerMonth - the number of days per one month
+   * @param cal          - the checked interval
+   * @param daysPerMonth - the number of days per one month. The default value is 31 days
+   *                       per month. This value was taken as the default because it is used
+   *                       in Structured Streaming for watermark calculations. Having 31 days
+   *                       per month, we can guarantee that events are not dropped before
+   *                       the end of any month (February with 29 days or January with 31 days).
    * @return true if duration of the given interval is less than 0 otherwise false
    */
   def isNegative(cal: CalendarInterval, daysPerMonth: Int = 31): Boolean = {