Add docs about scopes to lib.rs

src/lib.rs

@@ -31,6 +31,46 @@
 //! let result = result.to_string(scope).unwrap();
 //! println!("result: {}", result.to_rust_string_lossy(scope));
 //! ```
+//!
+//! # Design of Scopes
+//!
+//! Although the end is in sight, the design is still a bit in flux.
+//!
+//! The general idea is that the various scope classes mediate access to the v8
+//! Isolate and the various items on its heap (Local/Global handles,
+//! return/escape slots, etc.). At any point in time there exists only one scope
+//! object that is directly accessible, which guarantees that all interactions
+//! with the Isolate are safe.
+//!
+//! A Scope as such is not a trait (there is currently an internal
+//! ScopeDefinition trait but that's only there to make implementation easier).
+//!
+//! Rather, there are a number of traits that are implemented for the scopes
+//! they're applicable to, you've probably seen most of them already. The
+//! InIsolate which gives access to &mut Isolate is implemented for all scopes,
+//! ToLocal (I might rename that) is implemented for all Scopes in which new
+//! Local handles can be created and it sets the appropriate lifetime on them.
+//! InContext means that a context has been entered (I'll make sure they have a
+//! get_context() method), etc.
+//!
+//! Furthermore, many callbacks will receive receive an appropriate Scope object
+//! as their first argument, which 'encodes' the the state the isolate is in
+//! when the callback is called. E.g. a FunctionCallbackScope implements
+//! InIsolate + InContext + (there is an active context) and ToLocal (it acts as
+//! a handlescope). HostImportModuleDynamicallyScope would also implement
+//! InIsolate + InContext plus EscapeLocal (it doesn't act like a HandleScope,
+//! but it lets you safely escape one MaybeLocal which is returned to the
+//! caller.
+//!
+//! In a nutshell, that's it.
+//!
+//! Open TODOs are:
+//! - Add these automatic scopes to more callbacks (in progress) and get rid of
+//!   the necessity to import the MapFnTo trait.
+//! - Fully integrate TryCatch blocks into the scope system (currently a
+//!   TryCatch works like a scope internally but it's not integrated).
+//! - Add methods to some on some of the scopes like get_context() for ContextScope.
+//! - Rename/reorganize/document.
 
 #![allow(clippy::missing_safety_doc)]
 #![allow(dead_code)]