Complete Rust API and migration documentation (#102)

crates/libremetaverse/examples/cancellation.rs

@@ -0,0 +1,14 @@
+use libremetaverse_types::compat::CancellationTokenSource;
+
+#[tokio::main(flavor = "current_thread")]
+async fn main() -> Result<(), libremetaverse::Error> {
+    let source = CancellationTokenSource::new();
+    let token = source.token();
+    source.cancel();
+    token.cancelled().await;
+    assert!(matches!(
+        token.throw_if_cancellation_requested(),
+        Err(libremetaverse::Error::Cancelled)
+    ));
+    Ok(())
+}

crates/libremetaverse/examples/offline_client.rs

@@ -0,0 +1,10 @@
+use libremetaverse::{ClientLifecycleState, GridClient};
+
+fn main() -> Result<(), libremetaverse::Error> {
+    let client = GridClient::new()?;
+    assert_eq!(client.lifecycle_state(), ClientLifecycleState::Active);
+    client.dispose_with_method()?;
+    client.dispose_with_method()?;
+    assert_eq!(client.lifecycle_state(), ClientLifecycleState::Disposed);
+    Ok(())
+}

crates/libremetaverse/src/lib.rs

@@ -1,4 +1,10 @@
-//! Public rewrite shell corresponding to the main `LibreMetaverse` assembly.
+//! Native Rust grid client corresponding to the main `LibreMetaverse` assembly.
+//!
+//! Start here for login, networking, agents, inventory, assets, appearance,
+//! world, and social APIs. The appended guide covers crate selection, C# name
+//! migration, ownership, cancellation, events, security, and `OpenSim` setup.
+
+#![doc = include_str!("../../../docs/rust-api-guide.md")]
 
 extern crate self as libremetaverse;