feat: add support of @example name

Parse <caption>$name</caption> for @example tag as specified in jsdoc

lib/deno_doc.generated.js

@@ -1,7 +1,7 @@
 // @generated file from wasmbuild -- do not edit
 // deno-lint-ignore-file
 // deno-fmt-ignore-file
-// source-hash: 77711f824813addd84abc54d07593440b801756f
+// source-hash: f43b988499ec896157e5f850ba3f51e11e666c87
 let wasm;
 
 const cachedTextDecoder = new TextDecoder("utf-8", {
@@ -228,7 +228,7 @@ function makeMutClosure(arg0, arg1, dtor, f) {
 }
 function __wbg_adapter_46(arg0, arg1, arg2) {
   wasm
-    ._dyn_core__ops__function__FnMut__A____Output___R_as_wasm_bindgen__closure__WasmClosure___describe__invoke__hb3a7596ff5d8eafe(
+    ._dyn_core__ops__function__FnMut__A____Output___R_as_wasm_bindgen__closure__WasmClosure___describe__invoke__haf77dc7cf0257051(
       arg0,
       arg1,
       addHeapObject(arg2),
@@ -284,7 +284,7 @@ function handleError(f, args) {
   }
 }
 function __wbg_adapter_104(arg0, arg1, arg2, arg3) {
-  wasm.wasm_bindgen__convert__closures__invoke2_mut__hc2815ade821c01ce(
+  wasm.wasm_bindgen__convert__closures__invoke2_mut__h4b9e99f05a380340(
     arg0,
     arg1,
     addHeapObject(arg2),
@@ -415,14 +415,14 @@ const imports = {
       const ret = false;
       return ret;
     },
-    __wbindgen_is_function: function (arg0) {
-      const ret = typeof (getObject(arg0)) === "function";
-      return ret;
-    },
     __wbindgen_is_string: function (arg0) {
       const ret = typeof (getObject(arg0)) === "string";
       return ret;
     },
+    __wbindgen_is_function: function (arg0) {
+      const ret = typeof (getObject(arg0)) === "function";
+      return ret;
+    },
     __wbg_call_95d1ea488d03e4e8: function () {
       return handleError(function (arg0, arg1) {
         const ret = getObject(arg0).call(getObject(arg1));
@@ -605,8 +605,8 @@ const imports = {
       const ret = wasm.memory;
       return addHeapObject(ret);
     },
-    __wbindgen_closure_wrapper1170: function (arg0, arg1, arg2) {
-      const ret = makeMutClosure(arg0, arg1, 196, __wbg_adapter_46);
+    __wbindgen_closure_wrapper1224: function (arg0, arg1, arg2) {
+      const ret = makeMutClosure(arg0, arg1, 197, __wbg_adapter_46);
       return addHeapObject(ret);
     },
   },

lib/types.d.ts

@@ -283,6 +283,7 @@ export interface JsDocTagOnly extends JsDocTagBase {
 export interface JsDocTagDoc extends JsDocTagBase {
   kind: "category" | "deprecated" | "example";
   doc?: string;
+  name?: string;
 }
 
 export interface JsDocTagNamed extends JsDocTagBase {

src/js_doc.rs

@@ -5,7 +5,7 @@ use serde::Deserialize;
 use serde::Serialize;
 
 lazy_static! {
-  static ref JS_DOC_TAG_MAYBE_DOC_RE: Regex = Regex::new(r#"(?s)^\s*@(category|deprecated|example|tags)(?:\s+(.+))?"#).unwrap();
+  static ref JS_DOC_TAG_MAYBE_DOC_RE: Regex = Regex::new(r#"(?s)^\s*@(category|deprecated|example|tags)(\s<caption>(.+)</caption>)?(?:\s+(.+))?"#).unwrap();
   static ref JS_DOC_TAG_NAMED_RE: Regex = Regex::new(r#"(?s)^\s*@(callback|template)\s+([a-zA-Z_$]\S*)(?:\s+(.+))?"#).unwrap();
   static ref JS_DOC_TAG_NAMED_TYPED_RE: Regex = Regex::new(r#"(?s)^\s*@(prop(?:erty)?|typedef)\s+\{([^}]+)\}\s+([a-zA-Z_$]\S*)(?:\s+(.+))?"#).unwrap();
   static ref JS_DOC_TAG_ONLY_RE: Regex = Regex::new(r#"^\s*@(constructor|class|ignore|module|public|private|protected|readonly)"#).unwrap();
@@ -109,7 +109,11 @@ pub enum JsDocTag {
     #[serde(skip_serializing_if = "Option::is_none")]
     doc: Option<String>,
   },
+  /// `@example`
+  /// or `@example <caption>name</caption>`
   Example {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    name: Option<String>,
     #[serde(skip_serializing_if = "Option::is_none")]
     doc: Option<String>,
   },
@@ -257,11 +261,12 @@ impl From<String> for JsDocTag {
       }
     } else if let Some(caps) = JS_DOC_TAG_MAYBE_DOC_RE.captures(&value) {
       let kind = caps.get(1).unwrap().as_str();
-      let doc = caps.get(2).map(|m| m.as_str().to_string());
+      let name = caps.get(3).map(|m| m.as_str().to_string());
+      let doc = caps.get(4).map(|m| m.as_str().to_string());
       match kind {
         "category" => Self::Category { doc },
         "deprecated" => Self::Deprecated { doc },
-        "example" => Self::Example { doc },
+        "example" => Self::Example { name, doc },
         "tags" => Self::Tags {
           tags: doc
             .map(|s| s.split(',').map(|i| i.trim().to_string()).collect())

src/printer.rs

@@ -243,8 +243,18 @@ impl<'a> DocPrinter<'a> {
         )?;
         self.format_jsdoc_tag_maybe_doc(w, doc, indent)
       }
-      JsDocTag::Example { doc } => {
-        writeln!(w, "{}@{}", Indent(indent), colors::magenta("example"))?;
+      JsDocTag::Example { name, doc } => {
+        if let Some(name) = name {
+          writeln!(
+            w,
+            "{}@{} {}",
+            Indent(indent),
+            colors::magenta("example"),
+            colors::bold(name)
+          )?;
+        } else {
+          writeln!(w, "{}@{}", Indent(indent), colors::magenta("example"))?;
+        }
         self.format_jsdoc_tag_maybe_doc(w, doc, indent)
       }
       JsDocTag::Extends { type_ref, doc } => {