Docs: adding documentation for the new time zone functionality (#24080)

* added timezone override information.

* added usp.

* added some code comments.

* added more documentation of the date and time functionality.

* Update docs/sources/reference/timerange.md

Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

* some small adjustments.

* fixed comments according to feedback.

* Update packages/grafana-data/src/datetime/parser.ts

* Update packages/grafana-data/src/datetime/parser.ts

* Update packages/grafana-data/src/datetime/parser.ts

* fixed final feedback.

Co-authored-by: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

docs/sources/reference/timerange.md

@@ -54,6 +54,16 @@ From Dashboard settings, click the Timepicker tab. From here you can specify the
 
 Grafana offers the ability to override the `now` value on a per dashboard basis. Most commonly, this feature is used to accommodate known delays in data aggregation to avoid null values.
 
+### Time zone options
+Starting in version 7.0, you can override the time zone used to display date and time values in a dashboard. 
+
+With this feature, you can specify the local time zone of the service or system that you are monitoring. This can be helpful when monitoring a system or service that operates across several time zones.
+
+Apart from the standard [ISO 8601 time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) you can select the following options:
+
+* **Default**: The default selected time zone for the user profile or organization is used. If no time zone is specified for the user profile or the organization, then `Local browser time` is used.
+* **Local browser time**: The time zone configured for the viewing user browser is used. This is usually the same time zone as set on the computer.
+
 ## Panel time overrides and timeshift
 
 You can override the relative time range for individual panels, causing them to be different than what is selected in the Dashboard time picker in the upper right. This allows you to show metrics from different time periods or days at the same time.

packages/grafana-data/src/datetime/common.ts

@@ -1,17 +1,46 @@
 import { TimeZone, DefaultTimeZone } from '../types/time';
 
+/**
+ * The type describing date and time options. Used for all the helper functions
+ * available to parse or format date and time values.
+ *
+ * @public
+ */
 export interface DateTimeOptions {
+  /**
+   * Specify this if you want to override the timeZone used when parsing or formatting
+   * a date and time value. If no timeZone is set, the default timeZone for the current
+   * user is used.
+   */
   timeZone?: TimeZone;
 }
 
+/**
+ * The type to describe the time zone resolver function that will be used to access
+ * the default time zone of a user.
+ *
+ * @public
+ */
 export type TimeZoneResolver = () => TimeZone | undefined;
 
 let defaultTimeZoneResolver: TimeZoneResolver = () => DefaultTimeZone;
 
+/**
+ * Used by Grafana internals to set the {@link TimeZoneResolver} to access the current
+ * user timeZone.
+ *
+ * @internal
+ */
 export const setTimeZoneResolver = (resolver: TimeZoneResolver) => {
   defaultTimeZoneResolver = resolver ?? defaultTimeZoneResolver;
 };
 
+/**
+ * Used within this package to get timeZone from an options value. If timezone
+ * is not set in the options, then a default timeZone is be resolved instead.
+ *
+ * @internal
+ */
 export const getTimeZone = <T extends DateTimeOptions>(options?: T): TimeZone => {
   return options?.timeZone ?? defaultTimeZoneResolver() ?? DefaultTimeZone;
 };

packages/grafana-data/src/datetime/formatter.ts

@@ -5,28 +5,89 @@ import { DateTimeInput } from './moment_wrapper';
 import { DEFAULT_DATE_TIME_FORMAT, MS_DATE_TIME_FORMAT } from './formats';
 import { DateTimeOptions, getTimeZone } from './common';
 
+/**
+ * The type describing the options that can be passed to the {@link dateTimeFormat}
+ * helper function to control how the date and time value passed to the function is
+ * formatted.
+ *
+ * @public
+ */
 export interface DateTimeOptionsWithFormat extends DateTimeOptions {
+  /**
+   * Specify a {@link https://momentjs.com/docs/#/displaying/format | momentjs} format to
+   * use a custom formatting pattern of the date and time value. If no format is set,
+   * then {@link DEFAULT_DATE_TIME_FORMAT} is used.
+   */
   format?: string;
+
+  /**
+   * Set this value to `true` if you want to include milliseconds when formatting date and time
+   * values in the default {@link DEFAULT_DATE_TIME_FORMAT} format.
+   */
   defaultWithMS?: boolean;
 }
 
-export type DateTimeFormatter<T extends DateTimeOptions = DateTimeOptions> = (
+type DateTimeFormatter<T extends DateTimeOptions = DateTimeOptions> = (dateInUtc: DateTimeInput, options?: T) => string;
-  dateInUtc: DateTimeInput,
-  options?: T
-) => string;
 
+/**
+ * Helper function to format date and time according to the specified options. If no options
+ * are supplied, then default values are used. For more details, see {@link DateTimeOptionsWithFormat}.
+ *
+ * @param dateInUtc - date in UTC format, e.g. string formatted with UTC offset, UNIX epoch in seconds etc.
+ * @param options
+ *
+ * @public
+ */
 export const dateTimeFormat: DateTimeFormatter<DateTimeOptionsWithFormat> = (dateInUtc, options?) =>
   toTz(dateInUtc, getTimeZone(options)).format(getFormat(options));
 
+/**
+ * Helper function to format date and time according to the standard ISO format e.g. 2013-02-04T22:44:30.652Z.
+ * If no options are supplied, then default values are used. For more details, see {@link DateTimeOptionsWithFormat}.
+ *
+ * @param dateInUtc - date in UTC format, e.g. string formatted with UTC offset, UNIX epoch in seconds etc.
+ * @param options
+ *
+ * @public
+ */
 export const dateTimeFormatISO: DateTimeFormatter = (dateInUtc, options?) =>
   toTz(dateInUtc, getTimeZone(options)).format();
 
+/**
+ * Helper function to return elapsed time since passed date. The returned value will be formatted
+ * in a human readable format e.g. 4 years ago. If no options are supplied, then default values are used.
+ * For more details, see {@link DateTimeOptions}.
+ *
+ * @param dateInUtc - date in UTC format, e.g. string formatted with UTC offset, UNIX epoch in seconds etc.
+ * @param options
+ *
+ * @public
+ */
 export const dateTimeFormatTimeAgo: DateTimeFormatter = (dateInUtc, options?) =>
   toTz(dateInUtc, getTimeZone(options)).fromNow();
 
+/**
+ * Helper function to format date and time according to the Grafana default formatting, but it
+ * also appends the time zone abbreviation at the end e.g. 2020-05-20 13:37:00 CET. If no options
+ * are supplied, then default values are used. For more details please see {@link DateTimeOptions}.
+ *
+ * @param dateInUtc - date in UTC format, e.g. string formatted with UTC offset, UNIX epoch in seconds etc.
+ * @param options
+ *
+ * @public
+ */
 export const dateTimeFormatWithAbbrevation: DateTimeFormatter = (dateInUtc, options?) =>
   toTz(dateInUtc, getTimeZone(options)).format(`${DEFAULT_DATE_TIME_FORMAT} z`);
 
+/**
+ * Helper function to return only the time zone abbreviation for a given date and time value. If no options
+ * are supplied, then default values are used. For more details please see {@link DateTimeOptions}.
+ *
+ * @param dateInUtc - date in UTC format, e.g. string formatted with UTC offset, UNIX epoch in seconds etc.
+ * @param options
+ *
+ * @public
+ */
 export const timeZoneAbbrevation: DateTimeFormatter = (dateInUtc, options?) =>
   toTz(dateInUtc, getTimeZone(options)).format('z');
 

packages/grafana-data/src/datetime/parser.ts

@@ -5,15 +5,38 @@ import { DateTimeOptions, getTimeZone } from './common';
 import { parse, isValid } from './datemath';
 import { lowerCase } from 'lodash';
 
+/**
+ * The type that describes options that can be passed when parsing a date and time value.
+ * @public
+ */
 export interface DateTimeOptionsWhenParsing extends DateTimeOptions {
+  /**
+   * If the input is a Grafana quick date, e.g. now-6h, then you can specify this to control
+   * whether the last part of the date and time value is included or excluded.
+   *
+   * Example: now-6h and the current time is 12:20:00 if roundUp is set to true
+   * the returned DateTime value will be 06:00:00.
+   */
   roundUp?: boolean;
 }
 
-export type DateTimeParser<T extends DateTimeOptions = DateTimeOptions> = (
+type DateTimeParser<T extends DateTimeOptions = DateTimeOptions> = (value: DateTimeInput, options?: T) => DateTime;
-  value: DateTimeInput,
-  options?: T
-) => DateTime;
 
+/**
+ * Helper function to parse a number, text or Date to a DateTime value. If a timeZone is supplied the incoming value
+ * is parsed with that timeZone as a base. The only exception to this is if the passed value is in a UTC-based
+ * format. Then it will use UTC as the base. Examples on UTC-based values are Unix epoch and ISO formatted strings.
+ *
+ * It can also parse the Grafana quick date and time format, e.g. now-6h will be parsed as Date.now() - 6 hours and
+ * returned as a valid DateTime value.
+ *
+ * If no options are supplied, then default values are used. For more details please see {@link DateTimeOptions}.
+ *
+ * @param value - should be a parsable date and time value
+ * @param options
+ *
+ * @public
+ */
 export const dateTimeParse: DateTimeParser<DateTimeOptionsWhenParsing> = (value, options?): DateTime => {
   if (isDateTime(value)) {
     return value;