docs(JsRealm.execute_script): adding info and doc test about the isolate parameter (#18280)

1 files changed, 24 insertions, 1 deletions

diff --git a/core/runtime.rs b/core/runtime.rs
index f9f2e5523..8e1529569 100644
--- a/core/runtime.rs
+++ b/core/runtime.rs
@@ -2417,6 +2417,25 @@ impl JsRuntime {
 /// Every method of [`JsRealm`] will panic if you call it with a reference to a
 /// [`v8::Isolate`] other than the one that corresponds to the current context.
 ///
+/// In other words, the [`v8::Isolate`] parameter for all the related [`JsRealm`] methods
+/// must be extracted from the pre-existing [`JsRuntime`].
+///
+/// Example usage with the [`JsRealm::execute_script`] method:
+/// ```
+/// use deno_core::JsRuntime;
+/// use deno_core::RuntimeOptions;
+///
+/// let mut runtime = JsRuntime::new(RuntimeOptions::default());
+/// let new_realm = runtime
+///         .create_realm()
+///         .expect("Handle the error properly");
+/// let source_code = "var a = 0; a + 1";
+/// let result = new_realm
+///         .execute_script(runtime.v8_isolate(), "<anon>", source_code)
+///         .expect("Handle the error properly");
+/// # drop(result);
+/// ```
+///
 /// # Lifetime of the realm
 ///
 /// As long as the corresponding isolate is alive, a [`JsRealm`] instance will
@@ -2452,6 +2471,7 @@ impl JsRealm {
       .clone()
   }
 
+  /// For info on the [`v8::Isolate`] parameter, check [`JsRealm#panics`].
   pub fn handle_scope<'s>(
     &self,
     isolate: &'s mut v8::Isolate,
@@ -2459,6 +2479,7 @@ impl JsRealm {
     v8::HandleScope::with_context(isolate, &self.0)
   }
 
+  /// For info on the [`v8::Isolate`] parameter, check [`JsRealm#panics`].
   pub fn global_object<'s>(
     &self,
     isolate: &'s mut v8::Isolate,
@@ -2485,7 +2506,9 @@ impl JsRealm {
   /// Executes traditional JavaScript code (traditional = not ES modules) in the
   /// realm's context.
   ///
-  /// `name` can be a filepath or any other string, eg.
+  /// For info on the [`v8::Isolate`] parameter, check [`JsRealm#panics`].
+  ///
+  /// The `name` parameter can be a filepath or any other string. E.g.:
   ///
   ///   - "/some/file/path.js"
   ///   - "<anon>"