Top-level module API docs for neon::result.

src/result/mod.rs

@@ -1,16 +1,43 @@
-//! Represents JavaScript exceptions as a Rust `Result` type.
+//! Represents JavaScript exceptions as a Rust [`Result`](std::result) type.
+//!
+//! Most interactions with the JavaScript engine can throw a JavaScript exception. Neon APIs
+//! that can throw an exception are called _throwing APIs_ and return the type
+//! [`NeonResult`](NeonResult) (or its shorthand [`JsResult`](JsResult)).
+//!
+//! When a throwing API triggers a JavaScript exception, it returns an [Err](std::result::Result::Err)
+//! result. This indicates that the thread is now throwing, and allows Rust code to perform any
+//! cleanup—with an important restriction: **while the JavaScript thread is still throwing,
+//! you cannot call additional throwing APIs**. All throwing APIs immediately panic if called
+//! while the thread is already throwing.
+//!
+//! ## Example
+//!
+//! Neon functions typically use [`JsResult`](JsResult) for their return type. This
+//! example defines a function that extracts a property called `"message"` from an object,
+//! throwing an exception if the argument is not of the right type or extracting the property
+//! fails:
+//!
+//! ```ignore
+//! fn get_message(mut cx: FunctionContext) -> JsResult<JsValue> {
+//!     let obj: Handle<JsObject> = cx.argument(0)?;
+//!     let prop: Handle<JsValue> = obj.get(&mut cx, "message")?;
+//!     Ok(prop)
+//! }
+//! ```
 
 use context::Context;
 use handle::Handle;
 use std::fmt::{Display, Formatter, Result as FmtResult};
 use types::Value;
 
-/// An error sentinel type used by `NeonResult` (and `JsResult`) to indicate that the JavaScript engine
-/// has entered into a throwing state.
+/// A [unit type][unit] indicating that the JavaScript thread is throwing an exception.
 ///
-/// `Throw` deliberately does not implement `std::error::Error`, because it's generally not a good idea
-/// to chain JavaScript exceptions with other kinds of Rust errors, since entering into the throwing
-/// state means that the JavaScript engine is unavailable until the exception is handled.
+/// `Throw` deliberately does not implement [`std::error::Error`](std::error::Error). It's
+/// not recommended to chain JavaScript exceptions with other kinds of Rust errors,
+/// since throwing means that the JavaScript thread is unavailable until the exception
+/// is handled.
+///
+/// [unit]: https://doc.rust-lang.org/book/ch05-01-defining-structs.html#unit-like-structs-without-any-fields
 #[derive(Debug)]
 pub struct Throw;
 
@@ -20,14 +47,14 @@ impl Display for Throw {
     }
 }
 
-/// The result of a computation that might send the JS engine into a throwing state.
+/// The result type for throwing APIs.
 pub type NeonResult<T> = Result<T, Throw>;
 
-/// The result of a computation that produces a JavaScript value and might send the JS engine into a throwing state.
+/// A result type for throwing APIs that produce JavaScript values.
 pub type JsResult<'b, T> = NeonResult<Handle<'b, T>>;
 
-/// An extension trait for `Result` values that can be converted into `JsResult` values by throwing a JavaScript
-/// exception in the error case.
+/// Extension trait for converting Rust [`Result`](std::result::Result) values
+/// into [`JsResult`](JsResult) values by throwing JavaScript exceptions.
 pub trait JsResultExt<'a, V: Value> {
     fn or_throw<'b, C: Context<'b>>(self, cx: &mut C) -> JsResult<'a, V>;
 }