From 29fa5388f547e16596f71bfb2f0fd8e6b7021c2d Mon Sep 17 00:00:00 2001
From: Ry Dahl <ry@tinyclouds.org>
Date: Thu, 26 Dec 2019 21:14:59 -0500
Subject: [PATCH] Fix some docs (#140)
---
src/handle_scope.rs | 12 ++++++++++
src/module.rs | 2 +-
src/property.rs | 53 ++++++++++++++++++++++++++++++++++++++++++---
3 files changed, 63 insertions(+), 4 deletions(-)
diff --git a/src/handle_scope.rs b/src/handle_scope.rs
index 21b2c88f..a8056faa 100644
--- a/src/handle_scope.rs
+++ b/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]);
diff --git a/src/module.rs b/src/module.rs
index 66b901a6..c886ba80 100644
--- a/src/module.rs
+++ b/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 {
diff --git a/src/property.rs b/src/property.rs
index 137366d5..67915e03 100644
--- a/src/property.rs
+++ b/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() }
}