chore(docs): add more docs for luau typing

src/lune/builtins/datetime/date_time.rs

@@ -94,7 +94,7 @@ impl DateTime {
         }
     }
 
-    /// Returns a new `DateTime` using the given units from a UTC time. The
+    /// Returns a new `DateTime` using the given units from a local time. The
     /// values accepted are similar to those found in the time value table
     /// returned by `to_local_time`.
     ///

types/datetime.luau

@@ -1,4 +1,4 @@
--- TODO: Add docs
+-- TODO: Add more docs
 
 export type Locale = "en" | "de" | "es" | "fr" | "it" | "ja" | "pl" | "pt-br" | "pt" | "tr"
 
@@ -49,6 +49,7 @@ export type DateTime = {
 	toIsoDate: (self: DateTime) -> string,
 	toLocalTime: (self: DateTime) -> DateTimeValues,
 	toUniversalTime: (self: DateTime) -> DateTimeValues,
+
 	formatTime: (
 		self: DateTime,
 		timezone: Timezone,
@@ -66,6 +67,33 @@ export type DateTime = {
 
 	```lua
 	local DateTime = require("@lune/datetime")
+
+	-- Returns the current moment in time as a ISO 8601 string
+	DateTime.now():toIsoDate()
+
+	-- Returns the current moment in time as per the format template in French
+	DateTime.now():formatTime("utc", "%A, %d %B %Y", "fr")
+
+	-- Returns a specific moment in time as a DateTime instance
+	DateTime.fromLocalTime({
+		["year"] = 2023,
+		["month"] = "aug",
+		["day"] = 26,
+		["hour"] = 16,
+		["minute"] = 56,
+		["second"] = 28,
+		["millisecond"] = 892,
+	})
+
+	-- Returns the current local time as a DateTime instance
+	DateTime.fromLocalTime()
+
+	-- Returns a DateTime instance from a given float, where the whole denotes the 
+	-- seconds and the fraction denotes the milliseconds
+	DateTime.fromUnixTimestamp(871978212313.321)
+
+	-- Returns the current time in terms of UTC
+	DateTime.now():toUniversalTime() 
 	```
 ]=]
 local dateTime = {}
@@ -94,14 +122,57 @@ function dateTime.fromUnixTimestamp(unixTimestamp: number?): DateTime
 	return nil :: any
 end
 
+--[=[
+	@within DateTime
+
+	Returns a new `DateTime` using the given units from a UTC time. The
+    values accepted are similar to those found in the time value table
+    returned by `to_universal_time`.
+    
+    - 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.
+    - Time units (hour, minute, second, millisecond) that are outside their normal range are valid. For example, 90 minutes will cause the hour to roll over by 1; -10 seconds will cause the minute value to roll back by 1.
+    - Non-integer values are rounded down. For example, providing 2.5 hours will be equivalent to providing 2 hours, not 2 hours 30 minutes.
+    - Omitted values are assumed to be their lowest value in their normal range, except for year which defaults to 1970.
+
+	@param dateTime Optional values for the dateTime instance, defaults to the current time
+	@return A DateTime instance
+]=]
 function dateTime.fromUniversalTime(dateTime: DateTimeValues?): DateTime
 	return nil :: any
 end
 
+--[=[
+	@within DateTime
+
+	Returns a new `DateTime` using the given units from a local time. The
+    values accepted are similar to those found in the time value table
+    returned by `to_local_time`.
+    
+    - 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.
+    - Time units (hour, minute, second, millisecond) that are outside their normal range are valid. For example, 90 minutes will cause the hour to roll over by 1; -10 seconds will cause the minute value to roll back by 1.
+    - Non-integer values are rounded down. For example, providing 2.5 hours will be equivalent to providing 2 hours, not 2 hours 30 minutes.
+    - Omitted values are assumed to be their lowest value in their normal range, except for year which defaults to 1970.
+
+	@param dateTime Optional values for the dateTime instance, defaults to the current time
+	@return A DateTime instance
+]=]
 function dateTime.fromLocalTime(dateTime: DateTimeValues?): DateTime
 	return nil :: any
 end
 
+--[=[
+	@within DateTime
+
+	Returns a `DateTime` from an ISO 8601 date-time string in UTC
+    time, such as those returned by `to_iso_date`. If the
+    string parsing fails, the function returns `nil`.
+    
+    An example ISO 8601 date-time string would be `2020-01-02T10:30:45Z`,
+    which represents January 2nd 2020 at 10:30 AM, 45 seconds.
+
+	@param isoDate An ISO 8601 formatted string
+	@return A DateTime instance
+]=]
 function dateTime.fromIsoDate(iso_date: string): DateTime?
 	return nil :: any
 end