Add documentation options for extension!()

core/examples/op2.js

@@ -0,0 +1,3 @@
+globalThis.op2_sample = {
+  "use_state": (f) => Deno.core.ops.op_use_state(f),
+};

core/examples/op2.rs

@@ -0,0 +1,68 @@
+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::FsModuleLoader;
+use deno_core::JsRuntime;
+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(())
+}
+
+extension!(
+  op2_sample,
+  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"
+);
+
+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 current working directory")?,
+  )?;
+
+  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)
+}

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,20 @@ macro_rules! extension {
     $(, global_object_middleware = $global_object_middleware_fn:expr )?
     $(, external_references = [ $( $external_reference:expr ),* $(,)? ] )?
     $(, customizer = $customizer_fn:expr )?
+    $(, docs = $($docblocks:expr),+)?
     $(,)?
   ) => {
-    /// Extension struct for
-    #[doc = stringify!($name)]
-    /// .
+    $( $(#[doc = $docblocks])+ )?
+    /// An extension for use with the Deno JS runtime
+    /// To use it, provide it as an argument when instantiating your runtime:
+    ///
+    /// ```rust
+    #[doc = concat!("let mut extensions = vec![", stringify!($name), "::init_ops_and_esm()];")]
+    /// let mut js_runtime = JsRuntime::new(RuntimeOptions {
+    ///   extensions
+    /// })
+    /// ```
+    ///
     #[allow(non_camel_case_types)]
     pub struct $name {
     }
@@ -358,6 +369,11 @@ 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 ),+ )?
       {
@@ -368,6 +384,11 @@ 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 ),+ )?
       {
@@ -379,6 +400,11 @@ 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 ),+ )?
       {