API docs for neon::object module top-level.

src/object/mod.rs

@@ -1,4 +1,36 @@
 //! Traits for working with JavaScript objects.
+//!
+//! This module defines the [`Object`](Object) trait, which is implemented
+//! by all object types in the [JavaScript type hierarchy][hierarchy]. This
+//! trait provides key operations in the semantics of JavaScript objects,
+//! such as getting and setting an object's properties.
+//!
+//! ## Property Keys
+//!
+//! Object properties are accessed by a _property key_, which in JavaScript
+//! can be a string or [symbol][symbol]. (Neon does not yet have support for
+//! symbols.) For convenience, the [`PropertyKey`](PropertyKey) trait allows
+//! Neon programs to use various Rust string types, as well as numeric types,
+//! as keys when accessing object properties, converting the keys to strings
+//! as necessary:
+//!
+//! ```
+//! # use neon::prelude::*;
+//! fn set_and_check<'a>(
+//!     cx: &mut impl Context<'a>,
+//!     obj: Handle<'a, JsObject>
+//! ) -> JsResult<'a, JsValue> {
+//!     let value = cx.string("hello!");
+//!     // set property "17" with integer shorthand
+//!     obj.set(17, value)?;
+//!     // get property "17" with string shorthand
+//!     // returns the same value ("hello!")
+//!     obj.get("17")
+//! }
+//! ```
+//!
+//! [hierarchy]: crate::types#the-javascript-type-hierarchy
+//! [symbol]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol
 
 #[cfg(feature = "legacy-runtime")]
 pub(crate) mod class;