From 40f4ed3a3c6e9d0b27e70fb26815dd22e6b54b2b Mon Sep 17 00:00:00 2001
From: Scott Anderson <scott@influxdata.com>
Date: Wed, 24 Jun 2020 14:11:22 -0600
Subject: [PATCH] updated other date pkg functions with durations and examples

---
 .../flux/stdlib/built-in/misc/now.md          | 12 ++++++++-
 .../v2.0/reference/flux/stdlib/date/hour.md   | 26 ++++++++++++++++++-
 .../reference/flux/stdlib/date/microsecond.md | 26 ++++++++++++++++++-
 .../reference/flux/stdlib/date/millisecond.md | 26 ++++++++++++++++++-
 .../v2.0/reference/flux/stdlib/date/month.md  | 26 ++++++++++++++++++-
 .../reference/flux/stdlib/date/monthday.md    | 26 ++++++++++++++++++-
 .../reference/flux/stdlib/date/nanosecond.md  | 26 ++++++++++++++++++-
 .../reference/flux/stdlib/date/quarter.md     | 26 ++++++++++++++++++-
 .../reference/flux/stdlib/date/truncate.md    | 18 ++++++-------
 .../reference/flux/stdlib/date/weekday.md     | 26 ++++++++++++++++++-
 .../v2.0/reference/flux/stdlib/date/year.md   | 26 ++++++++++++++++++-
 .../reference/flux/stdlib/date/yearday.md     | 26 ++++++++++++++++++-
 12 files changed, 270 insertions(+), 20 deletions(-)

diff --git a/content/v2.0/reference/flux/stdlib/built-in/misc/now.md b/content/v2.0/reference/flux/stdlib/built-in/misc/now.md
index bcc5048c8..3b38aaf35 100644
--- a/content/v2.0/reference/flux/stdlib/built-in/misc/now.md
+++ b/content/v2.0/reference/flux/stdlib/built-in/misc/now.md
@@ -12,7 +12,7 @@ related:
   - /v2.0/reference/flux/stdlib/system/time/
 ---
 
-The `now()` function returns the current time (UTC).
+The `now()` function returns the current time (UTC) or the time defined in the `now` option.
 
 _**Function type:** Date/Time_  
 _**Output data type:** Time_
@@ -22,11 +22,21 @@ now()
 ```
 
 ## Examples
+
+##### Use the current UTC time as a query boundary
 ```js
 data
   |> range(start: -10h, stop: now())
 ```
 
+##### Return the now option time
+```js
+option now = () => 2020-01-01T00:00:00Z
+
+now()
+// Returns 2020-01-01T00:00:00.000000000Z
+```
+
 {{% note %}}
 #### now() vs system.time()
 `now()` returns the current UTC time.
diff --git a/content/v2.0/reference/flux/stdlib/date/hour.md b/content/v2.0/reference/flux/stdlib/date/hour.md
index efdf143e7..02bde42e7 100644
--- a/content/v2.0/reference/flux/stdlib/date/hour.md
+++ b/content/v2.0/reference/flux/stdlib/date/hour.md
@@ -29,5 +29,29 @@ date.hour(t: 2019-07-17T12:05:21.012Z)
 
 ### t
 The time to operate on.
+Use an absolute time or relative duration.
+Durations are relative to `now()`.
 
-_**Data type:** Time_
+_**Data type:** Time | Duration_
+
+## Examples
+
+##### Return the hour of a time value
+```js
+import "date"
+
+date.hour(t: 2020-02-11T12:21:03.293534940Z)
+
+// Returns 12
+```
+
+##### Return the hour of a relative duration
+```js
+import "date"
+
+option now = () => 2020-02-11T12:21:03.293534940Z
+
+date.hour(t: -8h)
+
+// Returns 4
+```
diff --git a/content/v2.0/reference/flux/stdlib/date/microsecond.md b/content/v2.0/reference/flux/stdlib/date/microsecond.md
index bd4cbba76..3b6def9d0 100644
--- a/content/v2.0/reference/flux/stdlib/date/microsecond.md
+++ b/content/v2.0/reference/flux/stdlib/date/microsecond.md
@@ -29,5 +29,29 @@ date.microsecond(t: 2019-07-17T12:05:21.012934584Z)
 
 ### t
 The time to operate on.
+Use an absolute time or relative duration.
+Durations are relative to `now()`.
 
-_**Data type:** Time_
+_**Data type:** Time | Duration_
+
+## Examples
+
+##### Return the microsecond of a time value
+```js
+import "date"
+
+date.microsecond(t: 2020-02-11T12:21:03.293534940Z)
+
+// Returns 293534
+```
+
+##### Return the microsecond of a relative duration
+```js
+import "date"
+
+option now = () => 2020-02-11T12:21:03.293534940Z
+
+date.microsecond(t: -1890us)
+
+// Returns 291644
+```
diff --git a/content/v2.0/reference/flux/stdlib/date/millisecond.md b/content/v2.0/reference/flux/stdlib/date/millisecond.md
index 6d7a6285e..31496d092 100644
--- a/content/v2.0/reference/flux/stdlib/date/millisecond.md
+++ b/content/v2.0/reference/flux/stdlib/date/millisecond.md
@@ -29,5 +29,29 @@ date.millisecond(t: 2019-07-17T12:05:21.012934584Z)
 
 ### t
 The time to operate on.
+Use an absolute time or relative duration.
+Durations are relative to `now()`.
 
-_**Data type:** Time_
+_**Data type:** Time | Duration_
+
+## Examples
+
+##### Return the millisecond of a time value
+```js
+import "date"
+
+date.millisecond(t: 2020-02-11T12:21:03.293534940Z)
+
+// Returns 293
+```
+
+##### Return the millisecond of a relative duration
+```js
+import "date"
+
+option now = () => 2020-02-11T12:21:03.293534940Z
+
+date.millisecond(t: -150ms)
+
+// Returns 143
+```
diff --git a/content/v2.0/reference/flux/stdlib/date/month.md b/content/v2.0/reference/flux/stdlib/date/month.md
index 6612dedd4..01330e261 100644
--- a/content/v2.0/reference/flux/stdlib/date/month.md
+++ b/content/v2.0/reference/flux/stdlib/date/month.md
@@ -29,5 +29,29 @@ date.month(t: 2019-07-17T12:05:21.012Z)
 
 ### t
 The time to operate on.
+Use an absolute time or relative duration.
+Durations are relative to `now()`.
 
-_**Data type:** Time_
+_**Data type:** Time | Duration_
+
+## Examples
+
+##### Return the month of a time value
+```js
+import "date"
+
+date.month(t: 2020-02-11T12:21:03.293534940Z)
+
+// Returns 2
+```
+
+##### Return the month of a relative duration
+```js
+import "date"
+
+option now = () => 2020-02-11T12:21:03.293534940Z
+
+date.month(t: -3mo)
+
+// Returns 11
+```
diff --git a/content/v2.0/reference/flux/stdlib/date/monthday.md b/content/v2.0/reference/flux/stdlib/date/monthday.md
index fabc7d31b..36684343f 100644
--- a/content/v2.0/reference/flux/stdlib/date/monthday.md
+++ b/content/v2.0/reference/flux/stdlib/date/monthday.md
@@ -29,5 +29,29 @@ date.monthDay(t: 2019-07-17T12:05:21.012Z)
 
 ### t
 The time to operate on.
+Use an absolute time or relative duration.
+Durations are relative to `now()`.
 
-_**Data type:** Time_
+_**Data type:** Time | Duration_
+
+## Examples
+
+##### Return the day of the month for a time value
+```js
+import "date"
+
+date.monthDay(t: 2020-02-11T12:21:03.293534940Z)
+
+// Returns 11
+```
+
+##### Return the day of the month for a relative duration
+```js
+import "date"
+
+option now = () => 2020-02-11T12:21:03.293534940Z
+
+date.monthDay(t: -8d)
+
+// Returns 3
+```
diff --git a/content/v2.0/reference/flux/stdlib/date/nanosecond.md b/content/v2.0/reference/flux/stdlib/date/nanosecond.md
index 9d05b1f72..846aa0129 100644
--- a/content/v2.0/reference/flux/stdlib/date/nanosecond.md
+++ b/content/v2.0/reference/flux/stdlib/date/nanosecond.md
@@ -29,5 +29,29 @@ date.nanosecond(t: 2019-07-17T12:05:21.012934584Z)
 
 ### t
 The time to operate on.
+Use an absolute time or relative duration.
+Durations are relative to `now()`.
 
-_**Data type:** Time_
+_**Data type:** Time | Duration_
+
+## Examples
+
+##### Return the nanosecond for a time value
+```js
+import "date"
+
+date.nanosecond(t: 2020-02-11T12:21:03.293534940Z)
+
+// Returns 293534940Z
+```
+
+##### Return the nanosecond for a relative duration
+```js
+import "date"
+
+option now = () => 2020-02-11T12:21:03.293534940Z
+
+date.nanosecond(t: -2111984ns)
+
+// Returns 291422956
+```
diff --git a/content/v2.0/reference/flux/stdlib/date/quarter.md b/content/v2.0/reference/flux/stdlib/date/quarter.md
index a2f05b0f9..5a225a4a9 100644
--- a/content/v2.0/reference/flux/stdlib/date/quarter.md
+++ b/content/v2.0/reference/flux/stdlib/date/quarter.md
@@ -29,5 +29,29 @@ date.quarter(t: 2019-07-17T12:05:21.012Z)
 
 ### t
 The time to operate on.
+Use an absolute time or relative duration.
+Durations are relative to `now()`.
 
-_**Data type:** Time_
+_**Data type:** Time | Duration_
+
+## Examples
+
+##### Return the quarter for a time value
+```js
+import "date"
+
+date.quarter(t: 2020-02-11T12:21:03.293534940Z)
+
+// Returns 1
+```
+
+##### Return the quarter for a relative duration
+```js
+import "date"
+
+option now = () => 2020-02-11T12:21:03.293534940Z
+
+date.quarter(t: -7mo)
+
+// Returns 3
+```
diff --git a/content/v2.0/reference/flux/stdlib/date/truncate.md b/content/v2.0/reference/flux/stdlib/date/truncate.md
index 43645f815..f2ef1cb3b 100644
--- a/content/v2.0/reference/flux/stdlib/date/truncate.md
+++ b/content/v2.0/reference/flux/stdlib/date/truncate.md
@@ -51,14 +51,14 @@ For example: `1s`, `1m`, `1h`.
 ```js
 import "date"
 
-date.truncate(t: "2019-06-03T13:59:01.000000000Z", unit: 1s)
-// Returns  2019-06-03T13:59:01.000000000Z
+date.truncate(t: 2019-06-03T13:59:01.000000000Z, unit: 1s)
+// Returns 2019-06-03T13:59:01.000000000Z
 
-date.truncate(t: "2019-06-03T13:59:01.000000000Z", unit: 1m)
-// Returns  2019-06-03T13:59:00.000000000Z
+date.truncate(t: 2019-06-03T13:59:01.000000000Z, unit: 1m)
+// Returns 2019-06-03T13:59:00.000000000Z
 
-date.truncate(t: "2019-06-03T13:59:01.000000000Z", unit: 1h)
-// Returns  2019-06-03T13:00:00.000000000Z
+date.truncate(t: 2019-06-03T13:59:01.000000000Z, unit: 1h)
+// Returns 2019-06-03T13:00:00.000000000Z
 ```
 
 ##### Truncate time values using durations
@@ -68,11 +68,11 @@ import "date"
 option now = () => 2020-01-01T00:00:30.500000000Z
 
 date.truncate(t: -30s, unit: 1s)
-// Returns  2019-12-31T23:59:30.000000000Z
+// Returns 2019-12-31T23:59:30.000000000Z
 
 date.truncate(t: -1m, unit: 1m)
-// Returns  2019-12-31T23:59:00.000000000Z
+// Returns 2019-12-31T23:59:00.000000000Z
 
 date.truncate(t: -1h, unit: 1h)
-// Returns  2019-12-31T23:00:00.000000000Z
+// Returns 2019-12-31T23:00:00.000000000Z
 ```
diff --git a/content/v2.0/reference/flux/stdlib/date/weekday.md b/content/v2.0/reference/flux/stdlib/date/weekday.md
index 6e6fdb18c..0afcf7c67 100644
--- a/content/v2.0/reference/flux/stdlib/date/weekday.md
+++ b/content/v2.0/reference/flux/stdlib/date/weekday.md
@@ -29,5 +29,29 @@ date.weekDay(t: 2019-07-17T12:05:21.012Z)
 
 ### t
 The time to operate on.
+Use an absolute time or relative duration.
+Durations are relative to `now()`.
 
-_**Data type:** Time_
+_**Data type:** Time | Duration_
+
+## Examples
+
+##### Return the day of the week for a time value
+```js
+import "date"
+
+date.weekDay(t: 2020-02-11T12:21:03.293534940Z)
+
+// Returns 2
+```
+
+##### Return the day of the week for a relative duration
+```js
+import "date"
+
+option now = () => 2020-02-11T12:21:03.293534940Z
+
+date.weekDay(t: -84h)
+
+// Returns 6
+```
diff --git a/content/v2.0/reference/flux/stdlib/date/year.md b/content/v2.0/reference/flux/stdlib/date/year.md
index f911a5976..fd452ed2f 100644
--- a/content/v2.0/reference/flux/stdlib/date/year.md
+++ b/content/v2.0/reference/flux/stdlib/date/year.md
@@ -27,5 +27,29 @@ date.year(t: 2019-07-17T12:05:21.012Z)
 
 ### t
 The time to operate on.
+Use an absolute time or relative duration.
+Durations are relative to `now()`.
 
-_**Data type:** Time_
+_**Data type:** Time | Duration_
+
+## Examples
+
+##### Return the year for a time value
+```js
+import "date"
+
+date.year(t: 2020-02-11T12:21:03.293534940Z)
+
+// Returns 2020
+```
+
+##### Return the year for a relative duration
+```js
+import "date"
+
+option now = () => 2020-02-11T12:21:03.293534940Z
+
+date.year(t: -14y)
+
+// Returns 2006
+```
diff --git a/content/v2.0/reference/flux/stdlib/date/yearday.md b/content/v2.0/reference/flux/stdlib/date/yearday.md
index 20df57afe..a7ff048fb 100644
--- a/content/v2.0/reference/flux/stdlib/date/yearday.md
+++ b/content/v2.0/reference/flux/stdlib/date/yearday.md
@@ -29,5 +29,29 @@ date.yearDay(t: 2019-07-17T12:05:21.012Z)
 
 ### t
 The time to operate on.
+Use an absolute time or relative duration.
+Durations are relative to `now()`.
 
-_**Data type:** Time_
+_**Data type:** Time | Duration_
+
+## Examples
+
+##### Return the day of the year for a time value
+```js
+import "date"
+
+date.yearDay(t: 2020-02-11T12:21:03.293534940Z)
+
+// Returns 42
+```
+
+##### Return the day of the year for a relative duration
+```js
+import "date"
+
+option now = () => 2020-02-11T12:21:03.293534940Z
+
+date.yearDay(t: -1mo)
+
+// Returns 11
+```