docs: more rust doc additions

src/context/mod.rs

@@ -316,7 +316,7 @@ pub trait Context<'a>: ContextInternal<'a> {
         JsBuffer::new(self, size)
     }
 
-    /// Create a `JsDate`. This prevents
+    /// Convenience method for creating a `JsDate` value.
     #[cfg(feature = "napi-5")]
     fn date(&mut self, value: impl Into<f64>) -> Result<Handle<'a, JsDate>, DateError> {
         JsDate::new(self, value)

src/types/date.rs

@@ -51,8 +51,8 @@ pub enum DateErrorKind {
 impl DateErrorKind {
     fn as_str(&self) -> &'static str {
         match *self {
-            DateErrorKind::Overflow => "Uncaught RangeError: Date overflow",
-            DateErrorKind::Underflow => "Uncaught RangeError: Date underflow",
+            DateErrorKind::Overflow => "Date overflow",
+            DateErrorKind::Underflow => "Date underflow",
         }
     }
 }
@@ -70,8 +70,8 @@ impl JsDate {
     /// The largest possible Date value, defined by ECMAScript. See https://www.ecma-international.org/ecma-262/5.1/#sec-15.7.3.2
     pub const MAX_VALUE: f64 = 8.64e15;
 
-    /// Create a new Date. It errors when `value` is an out of bounds JavaScript Date value. When `value`
-    /// is `NaN`, an invalid
+    /// Creates a new Date. It errors when `value` is outside the range of valid JavaScript Date values. When `value`
+    /// is `NaN`, the operation will succeed but with an invalid Date
     pub fn new<'a, C: Context<'a>, T: Into<f64>>(cx: &mut C, value: T) -> Result<Handle<'a, JsDate>, DateError> {
         let env = cx.env().to_raw();
         let time = value.into();
@@ -89,7 +89,8 @@ impl JsDate {
         Ok(date)
     }
 
-    /// Create a new Date with lossy conversion for out of bounds Date values.
+    /// Creates a new Date with lossy conversion for out of bounds Date values. Out of bounds
+    /// values will be treated as NaN
     pub fn new_lossy<'a, C: Context<'a>, V: Into<f64>>(cx: &mut C, value: V) -> Handle<'a, JsDate> {
         let env = cx.env().to_raw();
         let local = unsafe {
@@ -98,15 +99,16 @@ impl JsDate {
         Handle::new_internal(JsDate(local))
     }
 
-    /// Get the Date's value
+    /// Gets the Date's value. An invalid Date will return `std::f64::NaN`
     pub fn value<'a, C: Context<'a>>(self, cx: &mut C) -> f64 {
         let env = cx.env().to_raw();
         unsafe {
             neon_runtime::date::value(env, self.to_raw())
         }
     }
 
-    /// Check if the Date's value is valid
+    /// Checks if the Date's value is valid. A Date is valid if its value is between
+    /// `JsDate::MIN_VALUE` and `JsDate::MAX_VALUE` or if it is `NaN`
     pub fn is_valid<'a, C: Context<'a>>(self, cx: &mut C) -> bool {
         let value = self.value(cx);
         value <= JsDate::MAX_VALUE && value >= JsDate::MIN_VALUE

test/napi/lib/date.js

@@ -26,6 +26,10 @@ describe('JsDate', function() {
     assert.isUndefined(addon.try_new_lossy_date());
   });
 
+  it('should handle nan dates', function () {
+    assert.isUndefined(addon.nan_dates());
+  });
+
   it('should check if date is invalid', function () {
     const date = addon.create_and_get_invalid_date();
     assert.isNaN(date);

test/napi/src/js/date.rs

@@ -1,4 +1,4 @@
-use std::f64::NAN;
+use std::{f64::NAN};
 
 use neon::prelude::*;
 use neon::types::JsDate;
@@ -37,6 +37,18 @@ pub fn try_new_lossy_date(mut cx: FunctionContext) -> JsResult<JsUndefined> {
     Ok(cx.undefined())
 }
 
+pub fn nan_dates(mut cx: FunctionContext) -> JsResult<JsUndefined> {
+    let date_nan = JsDate::new(&mut cx, NAN).unwrap();
+    assert!(!date_nan.is_valid(&mut cx));
+    assert!(date_nan.value(&mut cx).is_nan());
+
+    let date_nan_lossy = JsDate::new_lossy(&mut cx, NAN);
+    assert!(!date_nan_lossy.is_valid(&mut cx));
+    assert!(date_nan_lossy.value(&mut cx).is_nan());
+
+    Ok(cx.undefined())
+}
+
 pub fn check_date_is_invalid(mut cx: FunctionContext) -> JsResult<JsBoolean> {
     let time = JsDate::MIN_VALUE - 1.0;
     let date = JsDate::new_lossy(&mut cx, time);

test/napi/src/lib.rs

@@ -157,6 +157,7 @@ fn main(mut cx: ModuleContext) -> NeonResult<()> {
     cx.export_function("check_date_is_valid", check_date_is_valid)?;
     cx.export_function("try_new_date", try_new_date)?;
     cx.export_function("try_new_lossy_date", try_new_lossy_date)?;
+    cx.export_function("nan_dates", nan_dates)?;
     cx.export_function("create_date_from_value", create_date_from_value)?;
     cx.export_function("create_and_get_invalid_date", create_and_get_invalid_date)?;