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>

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> = (
-  value: DateTimeInput,
-  options?: T
-) => DateTime;
+type DateTimeParser<T extends DateTimeOptions = DateTimeOptions> = (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;