Typedefs & docs improvements for DateTime

types/DateTime.luau

@@ -1,94 +1,102 @@
-export type Locale = "en" | "de" | "es" | "fr" | "it" | "ja" | "pl" | "pt-br" | "pt" | "tr"
+--[[
+	NOTE: We export a couple different DateTimeValues types below to ensure
+	that types are completely accurate, for method args milliseconds will
+	always be optional, but for return values millis are always included
 
-export type DateTimeValues = {
+	If we figure out some better strategy here where we can
-	--- Year(s), in the range 1400 -> 9999
+	export just a single type while maintaining accuracy we
-	year: number,
+	can change to that in a future breaking semver release
-	--- Month(s), in the range 1 -> 12
+]]
-	month: number,
+
-	--- Day(s), in the range 1 -> 31
+type OptionalMillisecond = {
-	day: number,
-	--- Hour(s), in the range 0 -> 23
-	hour: number,
-	--- Minute(s), in the range 0 -> 59
-	minute: number,
-	--- Second(s), in the range 0 -> 60, where 60 is a leap second
-	second: number,
-	--- Millisecond(s), in the range 0 -> 999
 	millisecond: number?,
 }
 
+type Millisecond = {
+	millisecond: number,
+}
+
+--[=[
+	@interface Locale
+	@within DateTime
+
+	Enum type representing supported DateTime locales.
+
+	Currently supported locales are:
+
+	- `en` - English
+	- `de` - German
+	- `es` - Spanish
+	- `fr` - French
+	- `it` - Italian
+	- `ja` - Japanese
+	- `pl` - Polish
+	- `pt-br` - Brazilian Portuguese
+	- `pt` - Portuguese
+	- `tr` - Turkish
+]=]
+export type Locale = "en" | "de" | "es" | "fr" | "it" | "ja" | "pl" | "pt-br" | "pt" | "tr"
+
+--[=[
+	@interface DateTimeValues
+	@within DateTime
+
+	Individual date & time values, representing the primitives that make up a `DateTime`.
+
+	This is a dictionary that will contain the following values:
+
+	- `year` - Year(s), in the range 1400 -> 9999
+	- `month` - Month(s), in the range 1 -> 12
+	- `day` - Day(s), in the range 1 -> 31
+	- `hour` - Hour(s), in the range 0 -> 23
+	- `minute` - Minute(s), in the range 0 -> 59
+	- `second` - Second(s), in the range 0 -> 60, where 60 is a leap second
+
+	An additional `millisecond` value may also be included,
+	and should be within the range `0 -> 999`, but is optional.
+
+	However, any method returning this type should be guaranteed
+	to include milliseconds - see individual methods to verify.
+]=]
+export type DateTimeValues = {
+	year: number,
+	month: number,
+	day: number,
+	hour: number,
+	minute: number,
+	second: number,
+}
+
+--[=[
+	@interface DateTimeValueArguments
+	@within DateTime
+
+	Alias for `DateTimeValues` with an optional `millisecond` value.
+
+	Refer to the `DateTimeValues` documentation for additional information.
+]=]
+export type DateTimeValueArguments = DateTimeValues & OptionalMillisecond
+
+--[=[
+	@interface DateTimeValueReturns
+	@within DateTime
+
+	Alias for `DateTimeValues` with a mandatory `millisecond` value.
+
+	Refer to the `DateTimeValues` documentation for additional information.
+]=]
+export type DateTimeValueReturns = DateTimeValues & Millisecond
+
 local DateTime = {
 	--- Number of seconds passed since the UNIX epoch.
-	unixTimestamp = 0,
+	unixTimestamp = (nil :: any) :: number,
 	--- Number of milliseconds passed since the UNIX epoch.
-	unixTimestampMillis = 0,
+	unixTimestampMillis = (nil :: any) :: number,
 }
 
 --[=[
 	@within DateTime
-
+	@tag Method
-	Formats this `DateTime` as an ISO 8601 date-time string.
-
-	Some examples of ISO 8601 date-time strings:
-
-	- `2020-02-22T18:12:08Z`
-	- `2000-01-31T12:34:56+05:00`
-	- `1970-01-01T00:00:00.055Z`
-
-	@return string -- The ISO 8601 formatted string
-]=]
-function DateTime.toIsoDate(self: DateTime): string
-	return nil :: any
-end
-
---[=[
-	@within DateTime
-
-	Extracts local time values from this `DateTime`.
-
-	The returned table contains the following values:
-
-	| Key           | Type     | Range          |
-	|---------------|----------|----------------|
-	| `year`        | `number` | `1400 -> 9999` |
-	| `month`       | `number` | `1 -> 12`      |
-	| `day`         | `number` | `1 -> 31`      |
-	| `hour`        | `number` | `0 -> 23`      |
-	| `minute`      | `number` | `0 -> 59`      |
-	| `second`      | `number` | `0 -> 60`      |
-	| `millisecond` | `number` | `0 -> 999`     |
-
-	@return DateTimeValues -- A table of DateTime values
-]=]
-function DateTime.toLocalTime(self: DateTime): DateTimeValues
-	return nil :: any
-end
-
---[=[
-	@within DateTime
-
-	Extracts UTC (universal) time values from this `DateTime`.
-
-	The returned table contains the following values:
-
-	| Key           | Type     | Range          |
-	|---------------|----------|----------------|
-	| `year`        | `number` | `1400 -> 9999` |
-	| `month`       | `number` | `1 -> 12`      |
-	| `day`         | `number` | `1 -> 31`      |
-	| `hour`        | `number` | `0 -> 23`      |
-	| `minute`      | `number` | `0 -> 59`      |
-	| `second`      | `number` | `0 -> 60`      |
-	| `millisecond` | `number` | `0 -> 999`     |
-
-	@return DateTimeValues -- A table of DateTime values
-]=]
-function DateTime.toUniversalTime(self: DateTime): DateTimeValues
-	return nil :: any
-end
-
---[=[
-	@within DateTime
 
 	Formats this `DateTime` using the given `formatString` and `locale`, as local time.
 
@@ -120,6 +128,7 @@ end
 
 --[=[
 	@within DateTime
+	@tag Method
 
 	Formats this `DateTime` using the given `formatString` and `locale`, as UTC (universal) time.
 
@@ -153,6 +162,72 @@ function DateTime.formatUniversalTime(
 	return nil :: any
 end
 
+--[=[
+	@within DateTime
+	@tag Method
+
+	Formats this `DateTime` as an ISO 8601 date-time string.
+
+	Some examples of ISO 8601 date-time strings are:
+
+	- `2020-02-22T18:12:08Z`
+	- `2000-01-31T12:34:56+05:00`
+	- `1970-01-01T00:00:00.055Z`
+
+	@return string -- The ISO 8601 formatted string
+]=]
+function DateTime.toIsoDate(self: DateTime): string
+	return nil :: any
+end
+
+--[=[
+	@within DateTime
+	@tag Method
+
+	Extracts separated local date & time values from this `DateTime`.
+
+	The returned table contains the following values:
+
+	| Key           | Type     | Range          |
+	|---------------|----------|----------------|
+	| `year`        | `number` | `1400 -> 9999` |
+	| `month`       | `number` | `1 -> 12`      |
+	| `day`         | `number` | `1 -> 31`      |
+	| `hour`        | `number` | `0 -> 23`      |
+	| `minute`      | `number` | `0 -> 59`      |
+	| `second`      | `number` | `0 -> 60`      |
+	| `millisecond` | `number` | `0 -> 999`     |
+
+	@return DateTimeValueReturns -- A table of DateTime values
+]=]
+function DateTime.toLocalTime(self: DateTime): DateTimeValueReturns
+	return nil :: any
+end
+
+--[=[
+	@within DateTime
+	@tag Method
+
+	Extracts separated UTC (universal) date & time values from this `DateTime`.
+
+	The returned table contains the following values:
+
+	| Key           | Type     | Range          |
+	|---------------|----------|----------------|
+	| `year`        | `number` | `1400 -> 9999` |
+	| `month`       | `number` | `1 -> 12`      |
+	| `day`         | `number` | `1 -> 31`      |
+	| `hour`        | `number` | `0 -> 23`      |
+	| `minute`      | `number` | `0 -> 59`      |
+	| `second`      | `number` | `0 -> 60`      |
+	| `millisecond` | `number` | `0 -> 999`     |
+
+	@return DateTimeValueReturns -- A table of DateTime values
+]=]
+function DateTime.toUniversalTime(self: DateTime): DateTimeValueReturns
+	return nil :: any
+end
+
 export type DateTime = typeof(DateTime)
 
 --[=[
@@ -202,6 +277,7 @@ local dateTime = {}
 
 --[=[
 	@within DateTime
+	@tag Constructor
 
 	Returns a `DateTime` representing the current moment in time.
 
@@ -213,6 +289,7 @@ end
 
 --[=[
 	@within DateTime
+	@tag Constructor
 
 	Creates a new `DateTime` from the given UNIX timestamp.
 
@@ -236,10 +313,11 @@ end
 
 --[=[
 	@within DateTime
+	@tag Constructor
 
 	Creates a new `DateTime` from the given date & time values table, in universal (UTC) time.
 
-	The given table must contains the following values:
+	The given table must contain the following values:
 
 	| Key      | Type     | Range          |
 	|----------|----------|----------------|
@@ -253,24 +331,28 @@ end
 	An additional `millisecond` value may also be included,
 	and should be within the range `0 -> 999`, but is optional.
 
+	Any non-integer values in the given table will be rounded down.
+
+	### Errors
+
 	This constructor is fallible and may throw an error in the following situations:
 
-	- Date units (year, month, day) that produce an invalid date will raise an error. For example, January 32nd or February 29th on a non-leap year.
+	- Date units (year, month, day) were given that produce an invalid date. For example, January 32nd or February 29th on a non-leap year.
-	- Non-integer values are rounded down. For example, providing 2.5 hours is equivalent to providing 2 hours, not 2 hours and 30 minutes.
 
 	@param values -- Table containing date & time values
 	@return DateTime -- The new DateTime object
 ]=]
-function dateTime.fromUniversalTime(values: DateTimeValues): DateTime
+function dateTime.fromUniversalTime(values: DateTimeValueArguments): DateTime
 	return nil :: any
 end
 
 --[=[
 	@within DateTime
+	@tag Constructor
 
 	Creates a new `DateTime` from the given date & time values table, in local time.
 
-	The given table must contains the following values:
+	The given table must contain the following values:
 
 	| Key      | Type     | Range          |
 	|----------|----------|----------------|
@@ -284,27 +366,33 @@ end
 	An additional `millisecond` value may also be included,
 	and should be within the range `0 -> 999`, but is optional.
 
+	Any non-integer values in the given table will be rounded down.
+
+	### Errors
+
 	This constructor is fallible and may throw an error in the following situations:
 
-	- Date units (year, month, day) that produce an invalid date will raise an error. For example, January 32nd or February 29th on a non-leap year.
+	- Date units (year, month, day) were given that produce an invalid date. For example, January 32nd or February 29th on a non-leap year.
-	- Non-integer values are rounded down. For example, providing 2.5 hours is equivalent to providing 2 hours, not 2 hours and 30 minutes.
 
 	@param values -- Table containing date & time values
 	@return DateTime -- The new DateTime object
 ]=]
-function dateTime.fromLocalTime(values: DateTimeValues): DateTime
+function dateTime.fromLocalTime(values: DateTimeValueArguments): DateTime
 	return nil :: any
 end
 
 --[=[
 	@within DateTime
+	@tag Constructor
 
 	Creates a new `DateTime` from an ISO 8601 date-time string.
 
+	### Errors
+
 	This constructor is fallible and may throw an error if the given
 	string does not strictly follow the ISO 8601 date-time string format.
 
-	Some examples of valid ISO 8601 date-time strings:
+	Some examples of valid ISO 8601 date-time strings are:
 
 	- `2020-02-22T18:12:08Z`
 	- `2000-01-31T12:34:56+05:00`