docs(datetime): polish module documentation (#4569)

datetime/day_of_year.ts

@@ -9,7 +9,7 @@ import { DAY } from "./constants.ts";
  * @param date Date to get the day of the year of.
  * @return Number of the day in the year in the local time zone.
  *
- * @example
+ * @example Basic usage
  * ```ts
  * import { dayOfYear } from "https://deno.land/std@$STD_VERSION/datetime/day_of_year.ts";
  *

datetime/difference.ts

@@ -23,6 +23,9 @@ export type DifferenceFormat = Partial<Record<Unit, number>>;
 
 /** Options for {@linkcode difference}. */
 export type DifferenceOptions = {
+  /**
+   * Units to calculate difference in. Defaults to all units.
+   */
   units?: Unit[];
 };
 
@@ -36,7 +39,7 @@ function calculateMonthsDifference(from: Date, to: Date): number {
 }
 
 /**
- * Calculates the difference of the 2 given dates in the given units. If the units
+ * Calculates the difference of the 2 given dates in various units. If the units
  * are omitted, it returns the difference in the all available units.
  *
  * @param from Year to calculate difference from.
@@ -74,6 +77,7 @@ function calculateMonthsDifference(from: Date, to: Date): number {
  * difference(date0, date1, { units: ["days", "months", "years"] });
  * // { days: 730, months: 23, years: 1 }
  * ```
+ * The `units` option defines which units to calculate the difference in.
  */
 export function difference(
   from: Date,

datetime/format.ts

@@ -62,6 +62,7 @@ export interface FormatOptions {
  *
  * format(date, "yyyy-MM-dd HH:mm:ss", { utc: true }); // "2019-01-20 05:34:23"
  * ```
+ * Enable UTC formatting by setting the `utc` option to `true`.
  */
 export function format(
   date: Date,

datetime/is_leap.ts

@@ -19,21 +19,16 @@ function isYearNumberALeapYear(yearNumber: number): boolean {
  * @param year The year in number or `Date` format.
  * @returns `true` if the given year is a leap year; `false` otherwise.
  *
- * @example Passing `Date` objects
+ * @example Basic usage
  * ```ts
  * import { isLeap } from "https://deno.land/std@$STD_VERSION/datetime/is_leap.ts";
  *
  * isLeap(new Date("1970-01-02")); // false
  *
- * isLeap(new Date("1972-01-02")); // true
- * ```
- *
- * @example Passing number values
- * ```ts
- * import { isLeap } from "https://deno.land/std@$STD_VERSION/datetime/is_leap.ts";
- *
  * isLeap(1970); // false
  *
+ * isLeap(new Date("1972-01-02")); // true
+ *
  * isLeap(1972); // true
  * ```
  *
@@ -63,18 +58,13 @@ export function isLeap(year: Date | number): boolean {
  * @param year The year in number or `Date` format.
  * @returns `true` if the given year is a leap year; `false` otherwise.
  *
- * @example Passing `Date` objects
+ * @example Basic usage
  * ```ts
  * import { isUtcLeap } from "https://deno.land/std@$STD_VERSION/datetime/is_leap.ts";
  *
  * isUtcLeap(new Date("2000-01-01")); // true
  *
  * isUtcLeap(new Date("December 31, 1999 23:59:59 GMT-01:00")); // true
- * ```
- *
- * @example Passing number values
- * ```ts
- * import { isUtcLeap } from "https://deno.land/std@$STD_VERSION/datetime/is_leap.ts";
  *
  * isUtcLeap(2000); // true
  *

datetime/mod.ts

@@ -4,20 +4,105 @@
 /**
  * Utilities for dealing with {@linkcode Date} objects.
  *
+ * ## Constants
+ *
+ * Constants such as {@linkcode SECOND}, {@linkcode MINUTE} and {@linkcode HOUR}
+ * can be found in the {@linkcode ./constants.ts | constants} module.
+ *
+ * ## Day of year
+ *
+ * {@linkcode dayOfYear} returns the number of the day in the year in the local
+ * timezone. {@linkcode dayOfYearUtc} does the same but in UTC time.
+ *
  * ```ts
- * import {
- *   dayOfYear,
- *   format,
- *   isLeap,
- * } from "https://deno.land/std@$STD_VERSION/datetime/mod.ts";
+ * import { dayOfYear } from "https://deno.land/std@$STD_VERSION/datetime/day_of_year.ts";
+ *
+ * dayOfYear(new Date("2019-03-11T03:24:00")); // 70
+ * ```
+ *
+ * ## Difference between dates
+ *
+ * {@linkcode difference} calculates the difference of the 2 given dates in
+ * various units.
+ *
+ * ```ts
+ * import { difference } from "https://deno.land/std@$STD_VERSION/datetime/difference.ts";
+ *
+ * const date0 = new Date("2018-05-14");
+ * const date1 = new Date("2020-05-13");
  *
- * const date = new Date("2020-07-10T03:24:00");
+ * difference(date0, date1);
+ * // {
+ * //   milliseconds: 63072000000,
+ * //   seconds: 63072000,
+ * //   minutes: 1051200,
+ * //   hours: 17520,
+ * //   days: 730,
+ * //   weeks: 104,
+ * //   months: 23,
+ * //   quarters: 7,
+ * //   years: 1
+ * // }
+ * ```
+ *
+ * ## Formatting date strings
+ *
+ * {@linkcode format} formats a date to a string with the specified format.
+ *
+ * ```ts
+ * import { format } from "https://deno.land/std@$STD_VERSION/datetime/format.ts";
+ *
+ * const date = new Date(2019, 0, 20, 16, 34, 23, 123);
+ *
+ * format(date, "dd-MM-yyyy"); // "20-01-2019"
+ *
+ * format(date, "MM-dd-yyyy HH:mm:ss.SSS"); // "01-20-2019 16:34:23.123"
+ *
+ * format(date, "'today:' yyyy-MM-dd"); // "today: 2019-01-20"
+ * ```
  *
- * dayOfYear(date); // 192
+ * ## Detecting leap years
+ *
+ * {@linkcode isLeap} returns whether the given year is a leap year.
+ * {@linkcode isUtcLeap} does the same but in UTC time.
+ *
+ * ```ts
+ * import { isLeap } from "https://deno.land/std@$STD_VERSION/datetime/is_leap.ts";
+ *
+ * isLeap(new Date("1970-01-02")); // false
+ *
+ * isLeap(1970); // false
+ *
+ * isLeap(new Date("1972-01-02")); // true
+ *
+ * isLeap(1972); // true
+ * ```
+ *
+ * ## Parsing date strings
+ *
+ * {@linkcode parse} parses a date string using the specified format string.
+ *
+ * ```ts
+ * import { parse } from "https://deno.land/std@$STD_VERSION/datetime/parse.ts";
+ *
+ * parse("20-01-2019", "dd-MM-yyyy"); // 2019-01-19T13:00:00.000Z
+ *
+ * parse("01-20-2019 04:34 PM", "MM-dd-yyyy hh:mm a"); // 2019-01-20T05:34:00.000Z
+ *
+ * parse("01-20-2019 16:34:23.123", "MM-dd-yyyy HH:mm:ss.SSS"); // 2019-01-20T05:34:23.123Z
+ * ```
+ *
+ * ## Week of year
+ *
+ * {@linkcode weekOfYear} returns the number of the week in the year in the local
+ * timezone.
+ *
+ * ```ts
+ * import { weekOfYear } from "https://deno.land/std@$STD_VERSION/datetime/week_of_year.ts";
  *
- * format(date, "dd-MM-yyyy"); // "10-07-2020"
+ * weekOfYear(new Date("2020-12-28T03:24:00")); // 53
  *
- * isLeap(date); // true
+ * weekOfYear(new Date("2020-07-10T03:24:00")); // 28
  * ```
  *
  * @module

datetime/parse.ts

@@ -34,7 +34,7 @@ import { DateTimeFormatter } from "./_date_time_formatter.ts";
  * @param formatString The date time string format.
  * @return The parsed date.
  *
- * @example
+ * @example Basic usage
  * ```ts
  * import { parse } from "https://deno.land/std@$STD_VERSION/datetime/parse.ts";
  *

datetime/week_of_year.ts

@@ -21,7 +21,7 @@ const Day = {
  * @param date Date to get the week number of.
  * @returns The week number of the provided date.
  *
- * @example
+ * @example Basic usage
  * ```ts
  * import { weekOfYear } from "https://deno.land/std@$STD_VERSION/datetime/week_of_year.ts";
  *