From 23af4dadf7cc5aba476468db5ed110b379927435 Mon Sep 17 00:00:00 2001
From: Richard Carson <r.carson@calian.com>
Date: Fri, 22 Sep 2023 14:23:38 -0400
Subject: [PATCH 01/19] Add documentation option for extension!

---
 core/examples/op2.js |  3 +++
 core/examples/op2.rs | 60 ++++++++++++++++++++++++++++++++++++++++++++
 core/extensions.rs   | 14 ++++++++---
 3 files changed, 74 insertions(+), 3 deletions(-)
 create mode 100644 core/examples/op2.js
 create mode 100644 core/examples/op2.rs

diff --git a/core/examples/op2.js b/core/examples/op2.js
new file mode 100644
index 000000000..a56f6eedb
--- /dev/null
+++ b/core/examples/op2.js
@@ -0,0 +1,3 @@
+globalThis.op2_sample = {
+    'use_state': (f) => Deno.core.ops.op_use_state(f)
+};
\ No newline at end of file
diff --git a/core/examples/op2.rs b/core/examples/op2.rs
new file mode 100644
index 000000000..f216ec443
--- /dev/null
+++ b/core/examples/op2.rs
@@ -0,0 +1,60 @@
+use anyhow::Context;
+use deno_core::resolve_path;
+use deno_core::v8;
+use deno_core::op2;
+use deno_core::extension;
+use deno_core::OpState;
+use deno_core::FsModuleLoader;
+use deno_core::JsRuntime;
+use deno_core::anyhow::Error;
+use std::rc::Rc;
+
+#[op2]
+fn op_use_state(state: &mut OpState, #[global] callback: v8::Global<v8::Function>) -> Result<(), Error> {
+    state.put(callback);
+    Ok(())
+}
+
+extension!(
+    op2_sample,
+    ops = [op_use_state],
+    esm_entry_point = "ext:op2_sample/op2.js",
+    esm = [ dir "examples", "op2.js" ],
+    docs = "A small sample extension demonstrating op2 usage", "Contains one op"
+);
+
+fn main() -> Result<(), Error> {
+    let module_name = "test.js";
+    let module_code = "
+        op2_sample.use_state(() => {
+            console.log('Hello World');
+        });
+    ".to_string();
+
+    let mut js_runtime = JsRuntime::new(deno_core::RuntimeOptions {
+        module_loader: Some(Rc::new(FsModuleLoader)),
+        extensions: vec![op2_sample::init_ops_and_esm()],
+        ..Default::default()
+    });
+
+    let main_module = resolve_path(
+      module_name,
+      &std::env::current_dir().context("Unable to get CWD")?,
+    )?;
+  
+    let future = async move {
+      let mod_id = js_runtime.load_main_module(
+        &main_module,
+        Some(deno_core::FastString::from(module_code))
+        ).await?;
+      let result = js_runtime.mod_evaluate(mod_id);
+      js_runtime.run_event_loop(false).await?;
+      result.await?
+    };
+  
+    tokio::runtime::Builder::new_current_thread()
+      .enable_all()
+      .build()
+      .unwrap()
+      .block_on(future)
+}
\ No newline at end of file
diff --git a/core/extensions.rs b/core/extensions.rs
index 64f89d528..0ce3e73c9 100644
--- a/core/extensions.rs
+++ b/core/extensions.rs
@@ -232,6 +232,7 @@ macro_rules! or {
 ///   my_extension,
 ///   ops = [ op_xyz ],
 ///   esm = [ "my_script.js" ],
+///   docs = "A small sample extension"
 /// );
 /// ```
 ///
@@ -249,6 +250,7 @@ macro_rules! or {
 ///  * event_loop_middleware: an event-loop middleware function (see [`ExtensionBuilder::event_loop_middleware`])
 ///  * global_template_middleware: a global template middleware function (see [`ExtensionBuilder::global_template_middleware`])
 ///  * global_object_middleware: a global object middleware function (see [`ExtensionBuilder::global_object_middleware`])
+///  * docs: comma separated list of toplevel #[doc=...] tags to be applied to the extension's resulting struct
 #[macro_export]
 macro_rules! extension {
   (
@@ -269,11 +271,11 @@ macro_rules! extension {
     $(, global_object_middleware = $global_object_middleware_fn:expr )?
     $(, external_references = [ $( $external_reference:expr ),* $(,)? ] )?
     $(, customizer = $customizer_fn:expr )?
+    $(, docs = $docblock:expr$(, $($docblocks:expr),+)?)?
     $(,)?
   ) => {
-    /// Extension struct for
-    #[doc = stringify!($name)]
-    /// .
+    $( #[doc = $docblock] )?
+    $( $( #[doc = $($docblocks)+])? )?
     #[allow(non_camel_case_types)]
     pub struct $name {
     }
@@ -358,6 +360,8 @@ macro_rules! extension {
       }
 
       #[allow(dead_code)]
+      /// Initialize this extension for use with CommonJS
+      /// For modules, use init_ops_and_esm instead 
       pub fn init_js_only $( <  $( $param : $type + 'static ),* > )? () -> $crate::Extension
       $( where $( $bound : $bound_type ),+ )?
       {
@@ -368,6 +372,8 @@ macro_rules! extension {
       }
 
       #[allow(dead_code)]
+      /// Initialize this extension for use with ES modules 
+      /// For CommonJS, use init_js_only instead
       pub fn init_ops_and_esm $( <  $( $param : $type + 'static ),+ > )? ( $( $( $options_id : $options_type ),* )? ) -> $crate::Extension
       $( where $( $bound : $bound_type ),+ )?
       {
@@ -379,6 +385,8 @@ macro_rules! extension {
       }
 
       #[allow(dead_code)]
+      /// Initialize this extension's OPs
+      /// See[OP2](https://docs.rs/deno_core/latest/deno_core/attr.op2.html)
       pub fn init_ops $( <  $( $param : $type + 'static ),+ > )? ( $( $( $options_id : $options_type ),* )? ) -> $crate::Extension
       $( where $( $bound : $bound_type ),+ )?
       {

From f5594ef4b4a174e0cc72751bbd49aafa70a49641 Mon Sep 17 00:00:00 2001
From: Richard Carson <r.carson@calian.com>
Date: Fri, 22 Sep 2023 14:38:25 -0400
Subject: [PATCH 02/19] Fix fmt

---
 core/examples/op2.rs | 97 ++++++++++++++++++++++++--------------------
 core/extensions.rs   |  4 +-
 2 files changed, 54 insertions(+), 47 deletions(-)

diff --git a/core/examples/op2.rs b/core/examples/op2.rs
index f216ec443..09ffbd7f9 100644
--- a/core/examples/op2.rs
+++ b/core/examples/op2.rs
@@ -1,60 +1,67 @@
 use anyhow::Context;
+use deno_core::anyhow::Error;
+use deno_core::extension;
+use deno_core::op2;
 use deno_core::resolve_path;
 use deno_core::v8;
-use deno_core::op2;
-use deno_core::extension;
-use deno_core::OpState;
 use deno_core::FsModuleLoader;
 use deno_core::JsRuntime;
-use deno_core::anyhow::Error;
+use deno_core::OpState;
 use std::rc::Rc;
 
 #[op2]
-fn op_use_state(state: &mut OpState, #[global] callback: v8::Global<v8::Function>) -> Result<(), Error> {
-    state.put(callback);
-    Ok(())
+fn op_use_state(
+  state: &mut OpState,
+  #[global] callback: v8::Global<v8::Function>,
+) -> Result<(), Error> {
+  state.put(callback);
+  Ok(())
 }
 
 extension!(
-    op2_sample,
-    ops = [op_use_state],
-    esm_entry_point = "ext:op2_sample/op2.js",
-    esm = [ dir "examples", "op2.js" ],
-    docs = "A small sample extension demonstrating op2 usage", "Contains one op"
+  op2_sample,
+  ops = [op_use_state],
+  esm_entry_point = "ext:op2_sample/op2.js",
+  esm = [ dir "examples", "op2.js" ],
+  docs = "A small sample extension demonstrating op2 usage", "Contains one op"
 );
 
 fn main() -> Result<(), Error> {
-    let module_name = "test.js";
-    let module_code = "
-        op2_sample.use_state(() => {
-            console.log('Hello World');
-        });
-    ".to_string();
-
-    let mut js_runtime = JsRuntime::new(deno_core::RuntimeOptions {
-        module_loader: Some(Rc::new(FsModuleLoader)),
-        extensions: vec![op2_sample::init_ops_and_esm()],
-        ..Default::default()
-    });
-
-    let main_module = resolve_path(
-      module_name,
-      &std::env::current_dir().context("Unable to get CWD")?,
-    )?;
-  
-    let future = async move {
-      let mod_id = js_runtime.load_main_module(
+  let module_name = "test.js";
+  let module_code = "
+      op2_sample.use_state(() => {
+          console.log('Hello World');
+      });
+  "
+  .to_string();
+
+  let mut js_runtime = JsRuntime::new(deno_core::RuntimeOptions {
+    module_loader: Some(Rc::new(FsModuleLoader)),
+    extensions: vec![op2_sample::init_ops_and_esm()],
+    ..Default::default()
+  });
+
+  let main_module = resolve_path(
+    module_name,
+    &std::env::current_dir().context("Unable to get CWD")?,
+  )?;
+
+  let future = async move {
+    let mod_id = js_runtime
+      .load_main_module(
         &main_module,
-        Some(deno_core::FastString::from(module_code))
-        ).await?;
-      let result = js_runtime.mod_evaluate(mod_id);
-      js_runtime.run_event_loop(false).await?;
-      result.await?
-    };
-  
-    tokio::runtime::Builder::new_current_thread()
-      .enable_all()
-      .build()
-      .unwrap()
-      .block_on(future)
-}
\ No newline at end of file
+        Some(deno_core::FastString::from(module_code)),
+      )
+      .await?;
+
+    let result = js_runtime.mod_evaluate(mod_id);
+    js_runtime.run_event_loop(false).await?;
+    result.await?
+  };
+
+  tokio::runtime::Builder::new_current_thread()
+    .enable_all()
+    .build()
+    .unwrap()
+    .block_on(future)
+}
diff --git a/core/extensions.rs b/core/extensions.rs
index 0ce3e73c9..8dbe4986e 100644
--- a/core/extensions.rs
+++ b/core/extensions.rs
@@ -361,7 +361,7 @@ macro_rules! extension {
 
       #[allow(dead_code)]
       /// Initialize this extension for use with CommonJS
-      /// For modules, use init_ops_and_esm instead 
+      /// For modules, use init_ops_and_esm instead
       pub fn init_js_only $( <  $( $param : $type + 'static ),* > )? () -> $crate::Extension
       $( where $( $bound : $bound_type ),+ )?
       {
@@ -372,7 +372,7 @@ macro_rules! extension {
       }
 
       #[allow(dead_code)]
-      /// Initialize this extension for use with ES modules 
+      /// Initialize this extension for use with ES modules
       /// For CommonJS, use init_js_only instead
       pub fn init_ops_and_esm $( <  $( $param : $type + 'static ),+ > )? ( $( $( $options_id : $options_type ),* )? ) -> $crate::Extension
       $( where $( $bound : $bound_type ),+ )?

From c2cc5577f65c51a6ec97ec7c1b2e9c35c2d39f1d Mon Sep 17 00:00:00 2001
From: Richard Carson <r.carson@calian.com>
Date: Fri, 22 Sep 2023 14:42:03 -0400
Subject: [PATCH 03/19] Fix fmt

---
 core/examples/op2.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/core/examples/op2.js b/core/examples/op2.js
index a56f6eedb..2be13eeb2 100644
--- a/core/examples/op2.js
+++ b/core/examples/op2.js
@@ -1,3 +1,3 @@
 globalThis.op2_sample = {
-    'use_state': (f) => Deno.core.ops.op_use_state(f)
+    "use_state": (f) => Deno.core.ops.op_use_state(f)
 };
\ No newline at end of file

From 34bb3d49011919a0efa9c3541cd04246bb455df7 Mon Sep 17 00:00:00 2001
From: Richard Carson <r.carson@calian.com>
Date: Fri, 22 Sep 2023 14:42:55 -0400
Subject: [PATCH 04/19] Fix fmt

---
 core/examples/op2.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/core/examples/op2.js b/core/examples/op2.js
index 2be13eeb2..ea01d8f3a 100644
--- a/core/examples/op2.js
+++ b/core/examples/op2.js
@@ -1,3 +1,3 @@
 globalThis.op2_sample = {
-    "use_state": (f) => Deno.core.ops.op_use_state(f)
+    "use_state": (f) => Deno.core.ops.op_use_state(f),
 };
\ No newline at end of file

From 04b9d30eb91c1b1a4c7abe6f5ea1d1cc5f62f3b7 Mon Sep 17 00:00:00 2001
From: Richard Carson <r.carson@calian.com>
Date: Fri, 22 Sep 2023 14:44:00 -0400
Subject: [PATCH 05/19] Fix fmt

---
 core/examples/op2.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/core/examples/op2.js b/core/examples/op2.js
index ea01d8f3a..5ff215361 100644
--- a/core/examples/op2.js
+++ b/core/examples/op2.js
@@ -1,3 +1,3 @@
 globalThis.op2_sample = {
-    "use_state": (f) => Deno.core.ops.op_use_state(f),
-};
\ No newline at end of file
+  "use_state": (f) => Deno.core.ops.op_use_state(f),
+};

From 1b657665d2a5edadee23ddc817291d46eb0bae87 Mon Sep 17 00:00:00 2001
From: Richard Carson <r.carson@calian.com>
Date: Fri, 22 Sep 2023 17:45:11 -0400
Subject: [PATCH 06/19] give more details in the docs

---
 core/examples/op2.rs |  2 +-
 core/extensions.rs   | 10 ++++++++++
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/core/examples/op2.rs b/core/examples/op2.rs
index 09ffbd7f9..217e9f6df 100644
--- a/core/examples/op2.rs
+++ b/core/examples/op2.rs
@@ -23,7 +23,7 @@ extension!(
   ops = [op_use_state],
   esm_entry_point = "ext:op2_sample/op2.js",
   esm = [ dir "examples", "op2.js" ],
-  docs = "A small sample extension demonstrating op2 usage", "Contains one op"
+  docs = "A small example demonstrating op2 usage", "Contains one op"
 );
 
 fn main() -> Result<(), Error> {
diff --git a/core/extensions.rs b/core/extensions.rs
index 8dbe4986e..b8f6be51d 100644
--- a/core/extensions.rs
+++ b/core/extensions.rs
@@ -276,6 +276,7 @@ macro_rules! extension {
   ) => {
     $( #[doc = $docblock] )?
     $( $( #[doc = $($docblocks)+])? )?
+    /// An extension for use with the Deno JS runtime
     #[allow(non_camel_case_types)]
     pub struct $name {
     }
@@ -362,6 +363,9 @@ macro_rules! extension {
       #[allow(dead_code)]
       /// Initialize this extension for use with CommonJS
       /// For modules, use init_ops_and_esm instead
+      /// 
+      /// # Returns
+      /// an Extension object that can be used during instantiation of a JsRuntime
       pub fn init_js_only $( <  $( $param : $type + 'static ),* > )? () -> $crate::Extension
       $( where $( $bound : $bound_type ),+ )?
       {
@@ -374,6 +378,9 @@ macro_rules! extension {
       #[allow(dead_code)]
       /// Initialize this extension for use with ES modules
       /// For CommonJS, use init_js_only instead
+      /// 
+      /// # Returns
+      /// an Extension object that can be used during instantiation of a JsRuntime
       pub fn init_ops_and_esm $( <  $( $param : $type + 'static ),+ > )? ( $( $( $options_id : $options_type ),* )? ) -> $crate::Extension
       $( where $( $bound : $bound_type ),+ )?
       {
@@ -387,6 +394,9 @@ macro_rules! extension {
       #[allow(dead_code)]
       /// Initialize this extension's OPs
       /// See[OP2](https://docs.rs/deno_core/latest/deno_core/attr.op2.html)
+      /// 
+      /// # Returns
+      /// an Extension object that can be used during instantiation of a JsRuntime
       pub fn init_ops $( <  $( $param : $type + 'static ),+ > )? ( $( $( $options_id : $options_type ),* )? ) -> $crate::Extension
       $( where $( $bound : $bound_type ),+ )?
       {

From 72cb8062de349f9e50ec8ecf4b3dfbf610c0bc41 Mon Sep 17 00:00:00 2001
From: Richard Carson <r.carson@calian.com>
Date: Fri, 22 Sep 2023 18:02:28 -0400
Subject: [PATCH 07/19] format didn't like the space in my docblock

---
 core/extensions.rs | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/core/extensions.rs b/core/extensions.rs
index b8f6be51d..a48c9a9b2 100644
--- a/core/extensions.rs
+++ b/core/extensions.rs
@@ -363,7 +363,7 @@ macro_rules! extension {
       #[allow(dead_code)]
       /// Initialize this extension for use with CommonJS
       /// For modules, use init_ops_and_esm instead
-      /// 
+      ///
       /// # Returns
       /// an Extension object that can be used during instantiation of a JsRuntime
       pub fn init_js_only $( <  $( $param : $type + 'static ),* > )? () -> $crate::Extension
@@ -378,7 +378,7 @@ macro_rules! extension {
       #[allow(dead_code)]
       /// Initialize this extension for use with ES modules
       /// For CommonJS, use init_js_only instead
-      /// 
+      ///
       /// # Returns
       /// an Extension object that can be used during instantiation of a JsRuntime
       pub fn init_ops_and_esm $( <  $( $param : $type + 'static ),+ > )? ( $( $( $options_id : $options_type ),* )? ) -> $crate::Extension
@@ -394,7 +394,7 @@ macro_rules! extension {
       #[allow(dead_code)]
       /// Initialize this extension's OPs
       /// See[OP2](https://docs.rs/deno_core/latest/deno_core/attr.op2.html)
-      /// 
+      ///
       /// # Returns
       /// an Extension object that can be used during instantiation of a JsRuntime
       pub fn init_ops $( <  $( $param : $type + 'static ),+ > )? ( $( $( $options_id : $options_type ),* )? ) -> $crate::Extension

From 41c45df117a93ca11279c5d650aa8cbc1c804e56 Mon Sep 17 00:00:00 2001
From: Richard Carson <Rscarson@rogers.com>
Date: Sat, 23 Sep 2023 13:18:30 -0400
Subject: [PATCH 08/19] Update core/examples/op2.rs

Co-authored-by: Matt Mastracci <matthew@mastracci.com>
---
 core/examples/op2.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/core/examples/op2.rs b/core/examples/op2.rs
index 217e9f6df..46dc8c2fe 100644
--- a/core/examples/op2.rs
+++ b/core/examples/op2.rs
@@ -43,7 +43,7 @@ fn main() -> Result<(), Error> {
 
   let main_module = resolve_path(
     module_name,
-    &std::env::current_dir().context("Unable to get CWD")?,
+    &std::env::current_dir().context("Unable to get current working directory")?,
   )?;
 
   let future = async move {

From bd7a87fc0c3d9ad9915cc44da9776f1b2ad8ce69 Mon Sep 17 00:00:00 2001
From: Richard Carson <r.carson@calian.com>
Date: Sat, 23 Sep 2023 13:53:18 -0400
Subject: [PATCH 09/19] Update docblock as per recommendation

---
 core/extensions.rs | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/core/extensions.rs b/core/extensions.rs
index a48c9a9b2..fa2716474 100644
--- a/core/extensions.rs
+++ b/core/extensions.rs
@@ -271,12 +271,20 @@ macro_rules! extension {
     $(, global_object_middleware = $global_object_middleware_fn:expr )?
     $(, external_references = [ $( $external_reference:expr ),* $(,)? ] )?
     $(, customizer = $customizer_fn:expr )?
-    $(, docs = $docblock:expr$(, $($docblocks:expr),+)?)?
+    $(, docs = $($docblocks:expr),+)?
     $(,)?
   ) => {
-    $( #[doc = $docblock] )?
-    $( $( #[doc = $($docblocks)+])? )?
+    $( $(#[doc = $docblocks])+ )?
     /// An extension for use with the Deno JS runtime
+    /// To use it, provide it as an argument when instantiating your runtime:
+    ///
+    /// ```rust
+    /// let mut extensions = vec![extension_name::init_ops_and_esm()];
+    /// let mut js_runtime = JsRuntime::new(RuntimeOptions {
+    ///   extensions
+    /// })
+    /// ```
+    ///
     #[allow(non_camel_case_types)]
     pub struct $name {
     }

From 4ccb5027d36e7f3641dd699bf026961c97a8355a Mon Sep 17 00:00:00 2001
From: Richard Carson <r.carson@calian.com>
Date: Sun, 24 Sep 2023 21:25:21 -0400
Subject: [PATCH 10/19] update docblock, fix fmt

---
 core/examples/op2.rs | 3 ++-
 core/extensions.rs   | 2 +-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/core/examples/op2.rs b/core/examples/op2.rs
index 46dc8c2fe..fca57b6ce 100644
--- a/core/examples/op2.rs
+++ b/core/examples/op2.rs
@@ -43,7 +43,8 @@ fn main() -> Result<(), Error> {
 
   let main_module = resolve_path(
     module_name,
-    &std::env::current_dir().context("Unable to get current working directory")?,
+    &std::env::current_dir()
+      .context("Unable to get current working directory")?,
   )?;
 
   let future = async move {
diff --git a/core/extensions.rs b/core/extensions.rs
index fa2716474..74b91ca95 100644
--- a/core/extensions.rs
+++ b/core/extensions.rs
@@ -279,7 +279,7 @@ macro_rules! extension {
     /// To use it, provide it as an argument when instantiating your runtime:
     ///
     /// ```rust
-    /// let mut extensions = vec![extension_name::init_ops_and_esm()];
+    #[doc = concat!("let mut extensions = vec![", stringify!($name), "::init_ops_and_esm()];")]
     /// let mut js_runtime = JsRuntime::new(RuntimeOptions {
     ///   extensions
     /// })

From 6a1d0296fc546e35b9c90b94d90628d1282c699e Mon Sep 17 00:00:00 2001
From: Richard Carson <Rscarson@rogers.com>
Date: Sun, 24 Sep 2023 22:34:19 -0400
Subject: [PATCH 11/19] Update core/extensions.rs

Co-authored-by: Matt Mastracci <matthew@mastracci.com>
---
 core/extensions.rs | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/core/extensions.rs b/core/extensions.rs
index 74b91ca95..e1ea5ae0b 100644
--- a/core/extensions.rs
+++ b/core/extensions.rs
@@ -275,7 +275,8 @@ macro_rules! extension {
     $(,)?
   ) => {
     $( $(#[doc = $docblocks])+ )?
-    /// An extension for use with the Deno JS runtime
+    ///
+    /// An extension for use with the Deno JS runtime.
     /// To use it, provide it as an argument when instantiating your runtime:
     ///
     /// ```rust

From c2d298b9e16d4b078d967538fab0a09548c5405a Mon Sep 17 00:00:00 2001
From: Richard Carson <Rscarson@rogers.com>
Date: Sun, 24 Sep 2023 22:34:50 -0400
Subject: [PATCH 12/19] Update core/examples/op2.rs

Co-authored-by: Matt Mastracci <matthew@mastracci.com>
---
 core/examples/op2.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/core/examples/op2.rs b/core/examples/op2.rs
index fca57b6ce..101e1800a 100644
--- a/core/examples/op2.rs
+++ b/core/examples/op2.rs
@@ -23,7 +23,7 @@ extension!(
   ops = [op_use_state],
   esm_entry_point = "ext:op2_sample/op2.js",
   esm = [ dir "examples", "op2.js" ],
-  docs = "A small example demonstrating op2 usage", "Contains one op"
+  docs = "A small example demonstrating op2 usage.", "Contains one op."
 );
 
 fn main() -> Result<(), Error> {

From 19646476f4e52425fdb0ab337b8326c2b0095970 Mon Sep 17 00:00:00 2001
From: Richard Carson <Rscarson@rogers.com>
Date: Sun, 24 Sep 2023 22:37:58 -0400
Subject: [PATCH 13/19] Update extensions.rs

---
 core/extensions.rs | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/core/extensions.rs b/core/extensions.rs
index e1ea5ae0b..89a389df8 100644
--- a/core/extensions.rs
+++ b/core/extensions.rs
@@ -280,6 +280,8 @@ macro_rules! extension {
     /// To use it, provide it as an argument when instantiating your runtime:
     ///
     /// ```rust
+    /// use deno_core::RuntimeOptions;
+    ///
     #[doc = concat!("let mut extensions = vec![", stringify!($name), "::init_ops_and_esm()];")]
     /// let mut js_runtime = JsRuntime::new(RuntimeOptions {
     ///   extensions

From 9d4df85b46c42b4446cd4e204dba1cce8099c4d3 Mon Sep 17 00:00:00 2001
From: Richard Carson <Rscarson@rogers.com>
Date: Sun, 24 Sep 2023 23:02:40 -0400
Subject: [PATCH 14/19] Update extensions.rs

---
 core/extensions.rs | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/core/extensions.rs b/core/extensions.rs
index 89a389df8..19141dfdb 100644
--- a/core/extensions.rs
+++ b/core/extensions.rs
@@ -284,7 +284,8 @@ macro_rules! extension {
     ///
     #[doc = concat!("let mut extensions = vec![", stringify!($name), "::init_ops_and_esm()];")]
     /// let mut js_runtime = JsRuntime::new(RuntimeOptions {
-    ///   extensions
+    ///   extensions,
+    ///   Default::default()
     /// })
     /// ```
     ///

From 7a5df1b7e84e15a6b920ff6875bec83096726f40 Mon Sep 17 00:00:00 2001
From: Richard Carson <Rscarson@rogers.com>
Date: Sun, 24 Sep 2023 23:19:53 -0400
Subject: [PATCH 15/19] Update extensions.rs

---
 core/extensions.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/core/extensions.rs b/core/extensions.rs
index 19141dfdb..6342eb72f 100644
--- a/core/extensions.rs
+++ b/core/extensions.rs
@@ -285,7 +285,7 @@ macro_rules! extension {
     #[doc = concat!("let mut extensions = vec![", stringify!($name), "::init_ops_and_esm()];")]
     /// let mut js_runtime = JsRuntime::new(RuntimeOptions {
     ///   extensions,
-    ///   Default::default()
+    ///   ..Default::default()
     /// })
     /// ```
     ///

From 331f2c716bd8b85a112df0508becda4bc4b45441 Mon Sep 17 00:00:00 2001
From: Richard Carson <r.carson@calian.com>
Date: Mon, 25 Sep 2023 09:59:45 -0400
Subject: [PATCH 16/19] Fix example in extensions

---
 core/extensions.rs | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/core/extensions.rs b/core/extensions.rs
index 6342eb72f..0a48b14c8 100644
--- a/core/extensions.rs
+++ b/core/extensions.rs
@@ -279,14 +279,14 @@ macro_rules! extension {
     /// An extension for use with the Deno JS runtime.
     /// To use it, provide it as an argument when instantiating your runtime:
     ///
-    /// ```rust
-    /// use deno_core::RuntimeOptions;
+    /// ```rust,ignore
+    /// use deno_core::{ JsRuntime, RuntimeOptions };
     ///
     #[doc = concat!("let mut extensions = vec![", stringify!($name), "::init_ops_and_esm()];")]
     /// let mut js_runtime = JsRuntime::new(RuntimeOptions {
     ///   extensions,
     ///   ..Default::default()
-    /// })
+    /// });
     /// ```
     ///
     #[allow(non_camel_case_types)]

From 468006e943876e15375df22c25bc92c0c1d0b965 Mon Sep 17 00:00:00 2001
From: Richard Carson <Rscarson@rogers.com>
Date: Tue, 26 Sep 2023 16:15:06 -0400
Subject: [PATCH 17/19] Update core/extensions.rs

Co-authored-by: Nayeem Rahman <nayeemrmn99@gmail.com>
---
 core/extensions.rs | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/core/extensions.rs b/core/extensions.rs
index 0a48b14c8..8a91f65f5 100644
--- a/core/extensions.rs
+++ b/core/extensions.rs
@@ -388,8 +388,10 @@ macro_rules! extension {
       }
 
       #[allow(dead_code)]
-      /// Initialize this extension for use with ES modules
-      /// For CommonJS, use init_js_only instead
+      /// Initialize this extension for runtime or snapshot creation. Use this
+      /// function if the runtime or snapshot is not created from a (separate)
+      /// snapshot, or that snapshot does not contain this extension. Otherwise
+      /// use `init_ops()` instead.
       ///
       /// # Returns
       /// an Extension object that can be used during instantiation of a JsRuntime

From 5e16d1f34b37dd2e6ff35c336aeb63f3ab96f0fc Mon Sep 17 00:00:00 2001
From: Richard Carson <Rscarson@rogers.com>
Date: Tue, 26 Sep 2023 16:15:20 -0400
Subject: [PATCH 18/19] Update core/extensions.rs

Co-authored-by: Nayeem Rahman <nayeemrmn99@gmail.com>
---
 core/extensions.rs | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/core/extensions.rs b/core/extensions.rs
index 8a91f65f5..baa4b5a56 100644
--- a/core/extensions.rs
+++ b/core/extensions.rs
@@ -406,8 +406,10 @@ macro_rules! extension {
       }
 
       #[allow(dead_code)]
-      /// Initialize this extension's OPs
-      /// See[OP2](https://docs.rs/deno_core/latest/deno_core/attr.op2.html)
+      /// Initialize this extension for runtime or snapshot creation, excluding
+      /// its JavaScript sources and evaluation. This is used when the runtime
+      /// or snapshot is created from a (separate) snapshot which includes this
+      /// extension in order to avoid evaluating the JavaScript twice.
       ///
       /// # Returns
       /// an Extension object that can be used during instantiation of a JsRuntime

From 977acd1a84dc667ed69e5207e4d52430e55ecff4 Mon Sep 17 00:00:00 2001
From: Richard Carson <r.carson@calian.com>
Date: Tue, 26 Sep 2023 16:20:08 -0400
Subject: [PATCH 19/19] Mark js_only as depr

---
 core/extensions.rs | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/core/extensions.rs b/core/extensions.rs
index baa4b5a56..2cd0ec690 100644
--- a/core/extensions.rs
+++ b/core/extensions.rs
@@ -373,11 +373,12 @@ macro_rules! extension {
       }
 
       #[allow(dead_code)]
-      /// Initialize this extension for use with CommonJS
-      /// For modules, use init_ops_and_esm instead
+      /// Legacy function for extension instantiation.
+      /// Please use `init_ops_and_esm` or `init_ops` instead
       ///
       /// # Returns
       /// an Extension object that can be used during instantiation of a JsRuntime
+      #[deprecated(since="0.216.0", note="please use `init_ops_and_esm` or `init_ops` instead")]
       pub fn init_js_only $( <  $( $param : $type + 'static ),* > )? () -> $crate::Extension
       $( where $( $bound : $bound_type ),+ )?
       {