doc: scaladoc DateColumn

core/src/main/scala/doric/syntax/DateColumns.scala

@@ -23,22 +23,24 @@ private[syntax] trait DateColumns {
   ) {
 
     /**
-      * Adds to the date the number of months
+      * Adds to the Date or Timestamp column the number of months
       *
       * @group Date & Timestamp Type
       * @param nMonths
       *   the number of months to add, can be negative to subtract.
       * @return
-      *   DoricColumn of the same type as the original with the month changed.
+      *   Date column after adding months
+      * @note Timestamp columns will be truncated to Date column
       */
     def addMonths(nMonths: IntegerColumn): DateColumn =
       (column.elem, nMonths.elem).mapN(f.add_months).toDC
 
     /**
-      * Returns the date that is `days` days after `start`
+      * Returns the date that is `days` days after date column
       *
-      * @param days A column of the number of days to add to `start`, can be negative to subtract days
+      * @param days A column of the number of days to add to date column, can be negative to subtract days
       * @group Date & Timestamp Type
+      * @note Timestamp columns will be truncated to Date column
       */
     def addDays(days: IntegerColumn): DateColumn =
       (column.elem, days.elem).mapN(f.date_add).toDC
@@ -60,19 +62,20 @@ private[syntax] trait DateColumns {
         .toDC
 
     /**
-      * Returns the date that is `days` days before `start`
+      * Returns the date that is `days` days before date column
       *
-      * @param days A column of the number of days to subtract from `start`, can be negative to add
+      * @param days A column of the number of days to subtract from date column, can be negative to add
       *             days
       * @group Date & Timestamp Type
+      * @note Timestamp columns will be truncated to Date column
       */
     def subDays(days: IntegerColumn): DateColumn =
       (column.elem, days.elem).mapN(f.date_sub).toDC
 
     /**
-      * Returns the number of days from `start` to `end`.
+      * Returns the number of days from date column to `dateCol`.
       *
-      * @param dateCol A date, timestamp or string. If a string, the data must be in a format that
+      * @param dateCol A Date or Timestamp column. If a string, the data must be in a format that
       *                can be cast to a date, such as `yyyy-MM-dd` or `yyyy-MM-dd HH:mm:ss.SSSS`
       * @group Date & Timestamp Type
       */
@@ -105,6 +108,7 @@ private[syntax] trait DateColumns {
 
     /**
       * Sets the moment to the last day of the same month.
+      *
       * @group Date & Timestamp Type
       */
     def endOfMonth: DateColumn = lastDayOfMonth
@@ -126,28 +130,28 @@ private[syntax] trait DateColumns {
     def month: IntegerColumn = column.elem.map(f.month).toDC
 
     /**
-      * Returns number of months between dates `start` and `end`.
+      * Returns number of months between dates date column and `dateCol`.
       *
       * A whole number is returned if both inputs have the same day of month or both are the last day
       * of their respective months. Otherwise, the difference is calculated assuming 31 days per month.
       *
       * For example:
       * {{{
-      * months_between("2017-11-14", "2017-07-14")  // returns 4.0
-      * months_between("2017-01-01", "2017-01-10")  // returns 0.29032258
-      * months_between("2017-06-01", "2017-06-16 12:00:00")  // returns -0.5
+      * Date("2017-11-14").monthsBetween(Date("2017-07-14"))                              // returns 4.0
+      * Date("2017-01-01").monthsBetween(Date("2017-01-10"))                              // returns 0.29032258
+      * Timestamp("2017-06-01 00:00:00").monthsBetween(Timestamp("2017-06-16 12:00:00"))  // returns -0.5
       * }}}
       *
-      * @param dateCol Date column
+      * @param dateCol Date or Timestamp column
       * @group Date & Timestamp Type
       */
     def monthsBetween(dateCol: DoricColumn[T]): DoubleColumn =
       (column.elem, dateCol.elem).mapN(f.months_between).toDC
 
     /**
-      * Returns number of months between dates `end` and `start`.
+      * Returns number of months between dates `dateCol` and date column.
       *
-      * @param dateCol Date column
+      * @param dateCol Date or Timestamp column
       * @param roundOff If `roundOff` is set to true, the result is rounded off to 8 digits;
       *                 it is not rounded otherwise.
       * @group Date & Timestamp Type
@@ -166,11 +170,12 @@ private[syntax] trait DateColumns {
       * Returns the first date which is later than the value of the `date` column that is on the
       * specified day of the week.
       *
-      * For example, `next_day('2015-07-27', "Sunday")` returns 2015-08-02 because that is the first
-      * Sunday after 2015-07-27.
+      * For example, `Date("2015-07-27").nextDay("Sunday")` returns Date("2015-08-02") because
+      * that is the first Sunday after 2015-07-27.
       *
       * @param dayOfWeek Case insensitive, and accepts: "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"
       * @group Date & Timestamp Type
+      * @note Timestamp columns will be truncated to Date column
       */
     def nextDay(dayOfWeek: StringColumn): DateColumn =
       (column.elem, dayOfWeek.elem)
@@ -189,12 +194,13 @@ private[syntax] trait DateColumns {
     /**
       * Returns date truncated to the unit specified by the format.
       *
-      * For example, `trunc("2018-11-19 12:01:19", "year")` returns 2018-01-01
+      * For example, `Timestamp("2018-11-19 12:01:19").trunc("year")` returns Date("2018-01-01")
       *
       * @param format 'year', 'yyyy', 'yy' to truncate by year,
       *               or 'month', 'mon', 'mm' to truncate by month
       *               Other options are: 'week', 'quarter'
       * @group Date & Timestamp Type
+      * @note Timestamp columns will be truncated to Date column
       */
     def trunc(format: StringColumn): DateColumn =
       (column.elem, format.elem)