Merge pull request #942 from neon-bindings/apidoc-examples

API docs improvements

.cargo/config.toml

@@ -3,5 +3,5 @@
 # The following aliases simplify linting the entire workspace
 neon-check = " check  --all --all-targets --features napi-experimental,futures,external-buffers"
 neon-clippy = "clippy --all --all-targets --features napi-experimental,futures,external-buffers -- -A clippy::missing_safety_doc"
-neon-test = "  test   --all               --features=doc-comment,napi-experimental,futures,external-buffers"
+neon-test = "  test   --all               --features=doc-dependencies,doc-comment,napi-experimental,futures,external-buffers"
 neon-doc = "   rustdoc -p neon            --features=doc-dependencies,napi-experimental,futures,external-buffers -- --cfg docsrs"

crates/neon/Cargo.toml

@@ -15,6 +15,7 @@ semver = "1"
 psd = "0.3.1"        # used for a doc example
 anyhow = "1.0.58"    # used for a doc example
 widestring = "1.0.2" # used for a doc example
+linkify = "0.9.0"    # used for a doc example
 
 [target.'cfg(not(target = "windows"))'.dev-dependencies]
 # Avoid `clang` as a dependency on windows
@@ -28,6 +29,7 @@ smallvec = "1.4.2"
 once_cell = "1.10.0"
 neon-macros = { version = "=1.0.0-alpha.2", path = "../neon-macros" }
 aquamarine = { version = "0.1.11", optional = true }
+easy-cast = { version = "0.5.1", optional = true }
 doc-comment = { version = "0.3.3", optional = true }
 
 [dependencies.tokio]
@@ -80,7 +82,7 @@ task-api = []
 proc-macros = []
 
 # Enables the optional dependencies that are only used for generating the API docs.
-doc-dependencies = ["doc-comment", "aquamarine"]
+doc-dependencies = ["doc-comment", "aquamarine", "easy-cast"]
 
 [package.metadata.docs.rs]
 rustdoc-args = ["--cfg", "docsrs"]

crates/neon/src/types_impl/boxed.rs

@@ -29,7 +29,7 @@ mod private {
     }
 }
 
-/// A smart pointer for Rust data managed by the JavaScript engine.
+/// A JavaScript smart pointer object that owns Rust data.
 ///
 /// The type `JsBox<T>` provides shared ownership of a value of type `T`,
 /// allocated in the heap. The data is owned by the JavaScript engine and the
@@ -281,8 +281,11 @@ impl<T: Send + 'static> Deref for JsBox<T> {
     }
 }
 
-/// Finalize is executed on the main JavaScript thread and executed immediately
-/// before garbage collection.
+/// A trait for finalizing values owned by the main JavaScript thread.
+///
+/// [`Finalize::finalize`] is executed on the main JavaScript thread
+/// immediately before garbage collection.
+///
 /// Values contained by a `JsBox` must implement `Finalize`.
 ///
 /// ## Examples

crates/neon/src/types_impl/buffer/types.rs

@@ -25,7 +25,9 @@ macro_rules! doc_comment {
     {$comment:expr, $decl:item} => { $decl };
 }
 
-/// The Node [`Buffer`](https://nodejs.org/api/buffer.html) type.
+/// The type of Node
+/// [`Buffer`](https://nodejs.org/api/buffer.html)
+/// objects.
 ///
 /// # Example
 ///
@@ -50,6 +52,8 @@ pub struct JsBuffer(raw::Local);
 
 impl JsBuffer {
     /// Constructs a new `Buffer` object, safely zero-filled.
+    ///
+    /// **See also:** [`Context::buffer`]
     pub fn new<'a, C: Context<'a>>(cx: &mut C, len: usize) -> JsResult<'a, Self> {
         let result = unsafe { sys::buffer::new(cx.env().to_raw(), len) };
 
@@ -206,7 +210,9 @@ impl TypedArray for JsBuffer {
     }
 }
 
-/// The standard JS [`ArrayBuffer`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) type.
+/// The type of JavaScript
+/// [`ArrayBuffer`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)
+/// objects.
 ///
 /// # Example
 ///
@@ -231,6 +237,8 @@ pub struct JsArrayBuffer(raw::Local);
 
 impl JsArrayBuffer {
     /// Constructs a new `JsArrayBuffer` object, safely zero-filled.
+    ///
+    /// **See also:** [`Context::array_buffer`]
     pub fn new<'a, C: Context<'a>>(cx: &mut C, len: usize) -> JsResult<'a, Self> {
         let result = unsafe { sys::arraybuffer::new(cx.env().to_raw(), len) };
 
@@ -420,7 +428,7 @@ pub trait Binary: private::Sealed + Copy {
     const TYPE_TAG: TypedArrayType;
 }
 
-/// The family of JS [typed array][typed-arrays] types.
+/// The family of JavaScript [typed array][typed-arrays] types.
 ///
 /// ## Typed Arrays
 ///
@@ -814,11 +822,11 @@ macro_rules! impl_typed_array {
 
         doc_comment! {
             concat!(
-                "The standard JS [`",
+                "The type of JavaScript [`",
                 stringify!($typ),
                 "`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/",
                 stringify!($typ),
-                ") type.
+                ") objects.
 
 # Example
 

crates/neon/src/types_impl/date.rs

@@ -13,7 +13,39 @@ use crate::{
     sys::{self, raw},
 };
 
-/// A JavaScript Date object
+/// The type of JavaScript
+/// [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
+/// objects.
+///
+/// # Example
+///
+/// The following shows an example of converting Rust
+/// [`SystemTime`](std::time::SystemTime) timestamps to JavaScript `Date` objects.
+///
+/// ```
+/// # use neon::prelude::*;
+/// use easy_cast::Cast; // for safe numeric conversions
+/// use neon::types::JsDate;
+/// use std::{error::Error, fs::File, time::SystemTime};
+///
+/// /// Return the "modified" timestamp for the file at the given path.
+/// fn last_modified(path: &str) -> Result<f64, Box<dyn Error>> {
+///     Ok(File::open(&path)?
+///         .metadata()?
+///         .modified()?
+///         .duration_since(SystemTime::UNIX_EPOCH)?
+///         .as_millis()
+///         .try_cast()?)
+/// }
+///
+/// fn modified(mut cx: FunctionContext) -> JsResult<JsDate> {
+///     let path: Handle<JsString> = cx.argument(0)?;
+///
+///     last_modified(&path.value(&mut cx))
+///         .and_then(|n| Ok(cx.date(n)?))
+///         .or_else(|err| cx.throw_error(err.to_string()))
+/// }
+/// ```
 #[cfg_attr(docsrs, doc(cfg(feature = "napi-5")))]
 #[derive(Debug)]
 #[repr(transparent)]
@@ -39,7 +71,7 @@ impl Managed for JsDate {
     }
 }
 
-/// The Error struct for a Date
+/// An error produced when constructing a date with an invalid value.
 #[derive(Debug)]
 #[cfg_attr(docsrs, doc(cfg(feature = "napi-5")))]
 pub struct DateError(DateErrorKind);
@@ -62,7 +94,11 @@ impl Error for DateError {}
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 #[cfg_attr(docsrs, doc(cfg(feature = "napi-5")))]
 pub enum DateErrorKind {
+    /// Produced for an initialization value greater than
+    /// [`JsDate::MAX_VALUE`](JsDate::MAX_VALUE).
     Overflow,
+    /// Produced for an initialization value lesser than
+    /// [`JsDate::MIN_VALUE`](JsDate::MIN_VALUE).
     Underflow,
 }
 
@@ -83,13 +119,16 @@ impl<'a, T: Value> ResultExt<Handle<'a, T>> for Result<Handle<'a, T>, DateError>
 }
 
 impl JsDate {
-    /// The smallest possible Date value, defined by ECMAScript. See <https://www.ecma-international.org/ecma-262/5.1/#sec-15.7.3.3>
+    /// The smallest possible `Date` value,
+    /// [defined by ECMAScript](https://www.ecma-international.org/ecma-262/5.1/#sec-15.7.3.3).
     pub const MIN_VALUE: f64 = -8.64e15;
-    /// The largest possible Date value, defined by ECMAScript. See <https://www.ecma-international.org/ecma-262/5.1/#sec-15.7.3.2>
+    /// The largest possible `Date` value,
+    /// [defined by ECMAScript](https://www.ecma-international.org/ecma-262/5.1/#sec-15.7.3.2).
     pub const MAX_VALUE: f64 = 8.64e15;
 
-    /// 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
+    /// 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,
@@ -108,22 +147,22 @@ impl JsDate {
         Ok(date)
     }
 
-    /// Creates a new Date with lossy conversion for out of bounds Date values. Out of bounds
-    /// values will be treated as NaN
+    /// 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 { sys::date::new_date(env, value.into()) };
         Handle::new_internal(JsDate(local))
     }
 
-    /// Gets the Date's value. An invalid Date will return `std::f64::NaN`
+    /// 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 { sys::date::value(env, self.to_raw()) }
     }
 
-    /// 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`
+    /// 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);
         (JsDate::MIN_VALUE..=JsDate::MAX_VALUE).contains(&value)

crates/neon/src/types_impl/error.rs

@@ -11,7 +11,30 @@ use crate::{
     types::{build, private::ValueInternal, utf8::Utf8, Value},
 };
 
-/// A JS `Error` object.
+/// The type of JavaScript
+/// [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)
+/// objects.
+///
+/// # Example
+///
+/// ```
+/// # use neon::prelude::*;
+/// # fn test(mut cx: FunctionContext) -> JsResult<JsUndefined> {
+/// // Create a type error:
+/// let err = cx.type_error("expected a number, found a string")?;
+///
+/// // Add some custom diagnostic properties to the error:
+/// let expected = cx.string("number");
+/// err.set(&mut cx, "expected", expected)?;
+///
+/// let found = cx.string("string");
+/// err.set(&mut cx, "found", found)?;
+///
+/// // Throw the error:
+/// cx.throw(err)?;
+/// # Ok(cx.undefined())
+/// # }
+/// ```
 #[repr(transparent)]
 #[derive(Debug)]
 pub struct JsError(raw::Local);
@@ -50,6 +73,8 @@ impl Object for JsError {}
 
 impl JsError {
     /// Creates a direct instance of the [`Error`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error) class.
+    ///
+    /// **See also:** [`Context::error`]
     pub fn error<'a, C: Context<'a>, S: AsRef<str>>(
         cx: &mut C,
         msg: S,
@@ -62,6 +87,8 @@ impl JsError {
     }
 
     /// Creates an instance of the [`TypeError`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/TypeError) class.
+    ///
+    /// **See also:** [`Context::type_error`]
     pub fn type_error<'a, C: Context<'a>, S: AsRef<str>>(
         cx: &mut C,
         msg: S,
@@ -74,6 +101,8 @@ impl JsError {
     }
 
     /// Creates an instance of the [`RangeError`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RangeError) class.
+    ///
+    /// **See also:** [`Context::range_error`]
     pub fn range_error<'a, C: Context<'a>, S: AsRef<str>>(
         cx: &mut C,
         msg: S,