add docs for date module (#61)

* add docs for date module (WIP)

* add docs for date module

* remove Date.valueOf, add more examples for Date.makeXY functions

* update CHANGELOG

* change type time to msSinceEpoch and add doc strings

* add examples for utc make functions

* fix formatting

* add more information about epoch

* added disclaimer to examples and fixed one example and its output

* fixed formatting of date module

Author: dkirchhof

CHANGELOG.md

@@ -13,6 +13,7 @@
 - Remove internal async/await helpers that do not need to be exposed in `Core`.
 - Add locale and formatting options to `localeDateString`, `localeString` and `localTimeString` functions https://github.com/rescript-association/rescript-core/pull/30
 - Change `RegExp.source` to return a `string`. Was previously returning a `bool`, which is wrong. https://github.com/rescript-association/rescript-core/pull/47
+- Remove `Date.valueOf` as it returns the same as `Date.getTime`. https://github.com/rescript-association/rescript-core/pull/61
 
 ### Documentation
 
@@ -24,3 +25,4 @@
 - Docstrings for `Int`. https://github.com/rescript-association/rescript-core/pull/37
 - Docstrings for `Dict`. https://github.com/rescript-association/rescript-core/pull/40
 - Docstrings for `RegExp`. https://github.com/rescript-association/rescript-core/pull/47
+- Docstrings for `Date`. https://github.com/rescript-association/rescript-core/pull/61

src/Core__Date.res

@@ -1,6 +1,6 @@
 type t = Js.Date.t
 
-type time = float
+type msSinceEpoch = float
 
 type localeOptions = {
   dateStyle?: [#full | #long | #medium | #short],
@@ -16,11 +16,9 @@ type localeOptions = {
   timeZoneName?: [#long | #short],
 }
 
-@send external valueOf: t => time = "valueOf"
-
 @new external make: unit => t = "Date"
 @new external fromString: string => t = "Date"
-@new external fromTime: time => t = "Date"
+@new external fromTime: msSinceEpoch => t = "Date"
 
 @new external makeWithYM: (~year: int, ~month: int) => t = "Date"
 @new external makeWithYMD: (~year: int, ~month: int, ~date: int) => t = "Date"
@@ -49,18 +47,19 @@ external makeWithYMDHMSM: (
 ) => t = "Date"
 
 module UTC = {
-  @val external makeWithYM: (~year: int, ~month: int) => time = "Date.UTC"
-  @val external makeWithYMD: (~year: int, ~month: int, ~date: int) => time = "Date.UTC"
+  @val external makeWithYM: (~year: int, ~month: int) => msSinceEpoch = "Date.UTC"
+  @val external makeWithYMD: (~year: int, ~month: int, ~date: int) => msSinceEpoch = "Date.UTC"
   @val
-  external makeWithYMDH: (~year: int, ~month: int, ~date: int, ~hours: int) => time = "Date.UTC"
+  external makeWithYMDH: (~year: int, ~month: int, ~date: int, ~hours: int) => msSinceEpoch =
+    "Date.UTC"
   @val
   external makeWithYMDHM: (
     ~year: int,
     ~month: int,
     ~date: int,
     ~hours: int,
     ~minutes: int,
-  ) => time = "Date.UTC"
+  ) => msSinceEpoch = "Date.UTC"
   @val
   external makeWithYMDHMS: (
     ~year: int,
@@ -69,7 +68,7 @@ module UTC = {
     ~hours: int,
     ~minutes: int,
     ~seconds: int,
-  ) => time = "Date.UTC"
+  ) => msSinceEpoch = "Date.UTC"
   @val
   external makeWithYMDHMSM: (
     ~year: int,
@@ -79,12 +78,12 @@ module UTC = {
     ~minutes: int,
     ~seconds: int,
     ~milliseconds: int,
-  ) => time = "Date.UTC"
+  ) => msSinceEpoch = "Date.UTC"
 }
 
-@val external now: unit => time = "Date.now"
+@val external now: unit => msSinceEpoch = "Date.now"
 
-@send external getTime: t => time = "getTime"
+@send external getTime: t => msSinceEpoch = "getTime"
 @send external getTimezoneOffset: t => int = "getTimezoneOffset"
 
 // Locale