Fix some docs (#140)

src/handle_scope.rs

@@ -32,6 +32,18 @@ extern "C" {
   ) -> &'sc mut Isolate;
 }
 
+/// A stack-allocated class that governs a number of local handles.
+/// After a handle scope has been created, all local handles will be
+/// allocated within that handle scope until either the handle scope is
+/// deleted or another handle scope is created.  If there is already a
+/// handle scope and a new one is created, all allocations will take
+/// place in the new handle scope until it is deleted.  After that,
+/// new handles will again be allocated in the original handle scope.
+///
+/// After the handle scope of a local handle has been deleted the
+/// garbage collector will no longer track the object stored in the
+/// handle and may deallocate it.  The behavior of accessing a handle
+/// for which the handle scope has been deleted is undefined.
 #[repr(C)]
 pub struct HandleScope([usize; 3]);
 

src/module.rs

@@ -75,10 +75,10 @@ pub enum ModuleStatus {
   Errored,
 }
 
+/// A compiled JavaScript module.
 #[repr(C)]
 pub struct Module(Opaque);
 
-/// A compiled JavaScript module.
 impl Module {
   /// Returns the module's current status.
   pub fn get_status(&self) -> ModuleStatus {

src/property.rs

@@ -6,6 +6,11 @@ use crate::ReturnValue;
 
 use std::mem::MaybeUninit;
 
+/// The information passed to a property callback about the context
+/// of the property access.
+#[repr(C)]
+pub struct PropertyCallbackInfo(Opaque);
+
 extern "C" {
   fn v8__PropertyCallbackInfo__GetIsolate(
     info: &PropertyCallbackInfo,
@@ -18,10 +23,12 @@ extern "C" {
   );
 }
 
-#[repr(C)]
-pub struct PropertyCallbackInfo(Opaque);
-
 impl PropertyCallbackInfo {
+  /// \return The return value of the callback.
+  /// Can be changed by calling Set().
+  /// \code
+  /// info.GetReturnValue().Set(...)
+  /// \endcode
   pub fn get_return_value(&self) -> ReturnValue {
     let mut rv = MaybeUninit::<ReturnValue>::uninit();
     unsafe {
@@ -30,10 +37,50 @@ impl PropertyCallbackInfo {
     }
   }
 
+  /// The isolate of the property access.
   pub fn get_isolate(&mut self) -> &mut Isolate {
     unsafe { v8__PropertyCallbackInfo__GetIsolate(self) }
   }
 
+  /// \return The receiver. In many cases, this is the object on which the
+  /// property access was intercepted. When using
+  /// `Reflect.get`, `Function.prototype.call`, or similar functions, it is the
+  /// object passed in as receiver or thisArg.
+  ///
+  /// \code
+  ///  void GetterCallback(Local<Name> name,
+  ///                      const v8::PropertyCallbackInfo<v8::Value>& info) {
+  ///     auto context = info.GetIsolate()->GetCurrentContext();
+  ///
+  ///     v8::Local<v8::Value> a_this =
+  ///         info.This()
+  ///             ->GetRealNamedProperty(context, v8_str("a"))
+  ///             .ToLocalChecked();
+  ///     v8::Local<v8::Value> a_holder =
+  ///         info.Holder()
+  ///             ->GetRealNamedProperty(context, v8_str("a"))
+  ///             .ToLocalChecked();
+  ///
+  ///    CHECK(v8_str("r")->Equals(context, a_this).FromJust());
+  ///    CHECK(v8_str("obj")->Equals(context, a_holder).FromJust());
+  ///
+  ///    info.GetReturnValue().Set(name);
+  ///  }
+  ///
+  ///  v8::Local<v8::FunctionTemplate> templ =
+  ///  v8::FunctionTemplate::New(isolate);
+  ///  templ->InstanceTemplate()->SetHandler(
+  ///      v8::NamedPropertyHandlerConfiguration(GetterCallback));
+  ///  LocalContext env;
+  ///  env->Global()
+  ///      ->Set(env.local(), v8_str("obj"), templ->GetFunction(env.local())
+  ///                                           .ToLocalChecked()
+  ///                                           ->NewInstance(env.local())
+  ///                                           .ToLocalChecked())
+  ///      .FromJust();
+  ///
+  ///  CompileRun("obj.a = 'obj'; var r = {a: 'r'}; Reflect.get(obj, 'x', r)");
+  /// \endcode
   pub fn this(&self) -> Local<Object> {
     unsafe { Local::from_raw(v8__PropertyCallbackInfo__This(self)).unwrap() }
   }