feat: add jsdoc summary and description tags

Author: crowlKats

src/html/jsdoc.rs

@@ -236,7 +236,20 @@ pub(crate) fn jsdoc_body_to_html(
   js_doc: &JsDoc,
   summary: bool,
 ) -> Option<String> {
-  if let Some(doc) = js_doc.doc.as_deref() {
+  if summary && let Some(doc) = js_doc.tags.iter().find_map(|tag| if let JsDocTag::Summary { doc } = tag {
+    Some(doc)
+  } else {
+    None
+  }) {
+    markdown_to_html(
+      ctx,
+      doc,
+      MarkdownToHTMLOptions {
+        title_only: false,
+        no_toc: false,
+      },
+    )
+  } else if let Some(doc) = js_doc.doc.as_deref() {
     markdown_to_html(
       ctx,
       doc,

src/js_doc.rs

@@ -11,7 +11,7 @@ lazy_static! {
   /// @tag maybe_value
   static ref JS_DOC_TAG_WITH_MAYBE_VALUE_RE: Regex = Regex::new(r"(?s)^\s*@(deprecated|module)(?:\s+(.+))?").unwrap();
   /// @tag value
-  static ref JS_DOC_TAG_WITH_VALUE_RE: Regex = Regex::new(r"(?s)^\s*@(category|group|see|example|tags|since|priority)(?:\s+(.+))").unwrap();
+  static ref JS_DOC_TAG_WITH_VALUE_RE: Regex = Regex::new(r"(?s)^\s*@(category|group|see|example|tags|since|priority|summary|description)(?:\s+(.+))").unwrap();
   /// @tag name maybe_value
   static ref JS_DOC_TAG_NAMED_WITH_MAYBE_VALUE_RE: Regex = Regex::new(r"(?s)^\s*@(callback|template|typeparam|typeParam)\s+([a-zA-Z_$]\S*)(?:\s+(.+))?").unwrap();
   /// @tag {type} name maybe_value
@@ -71,6 +71,7 @@ impl From<String> for JsDoc {
     let mut tag_is_codeblock = false;
     let mut current_tag: Option<String> = None;
     let mut current_tag_name = "";
+    let mut description_override: Option<String> = None;
     for line in value.lines() {
       let caps = JS_DOC_TAG_RE.captures(line);
       if is_tag || caps.is_some() {
@@ -82,7 +83,15 @@ impl From<String> for JsDoc {
           tag_is_codeblock = false;
           let current_tag = std::mem::take(&mut current_tag);
           if let Some(current_tag) = current_tag {
-            tags.push(current_tag.into());
+            if current_tag_name == "description" {
+              if let Some(caps) = JS_DOC_TAG_WITH_VALUE_RE.captures(&current_tag) {
+                if let Some(m) = caps.get(2) {
+                  description_override = Some(m.as_str().to_string());
+                }
+              }
+            } else {
+              tags.push(current_tag.into());
+            }
           }
         }
         if let Some(caps) = caps {
@@ -118,9 +127,22 @@ impl From<String> for JsDoc {
       }
     }
     if let Some(current_tag) = current_tag {
-      tags.push(current_tag.into());
+      if current_tag_name == "description" {
+        if let Some(rest) = current_tag.strip_prefix("@description") {
+          let desc = rest.trim_start();
+          if !desc.is_empty() {
+            description_override = Some(desc.to_string());
+          }
+        }
+      } else {
+        tags.push(current_tag.into());
+      }
     }
-    let doc = doc_lines.map(|doc_lines| doc_lines.into_boxed_str());
+    let doc = if let Some(desc) = description_override {
+      Some(desc.into_boxed_str())
+    } else {
+      doc_lines.map(|doc_lines| doc_lines.into_boxed_str())
+    };
     Self {
       doc,
       tags: tags.into_boxed_slice(),
@@ -270,6 +292,11 @@ pub enum JsDocTag {
   See {
     doc: Box<str>,
   },
+  /// `@summary comment`
+  Summary {
+    #[serde(default)]
+    doc: Box<str>,
+  },
   /// `@since version`
   Since {
     doc: Box<str>,
@@ -363,6 +390,7 @@ impl From<String> for JsDocTag {
         },
         "see" => Self::See { doc },
         "since" => Self::Since { doc },
+        "summary" => Self::Summary { doc },
         "priority" => {
           let Ok(priority) = doc.parse() else {
             return Self::Unsupported {
@@ -371,6 +399,7 @@ impl From<String> for JsDocTag {
           };
           Self::Priority { priority }
         }
+        "description" => unreachable!("@description is handled earlier"),
         _ => unreachable!("kind unexpected: {}", kind),
       }
     } else if let Some(caps) = JS_DOC_TAG_PARAM_RE.captures(&value) {
@@ -804,6 +833,69 @@ const a = "a";
 
       })
     );
+    assert_eq!(
+      serde_json::to_value(JsDoc::from(
+        "@summary A brief summary".to_string()
+      ))
+      .unwrap(),
+      json!({
+        "tags": [{
+          "kind": "summary",
+          "doc": "A brief summary",
+        }]
+      })
+    );
+  }
+
+  #[test]
+  fn test_js_doc_description_tag() {
+    // @description overrides the doc field
+    assert_eq!(
+      serde_json::to_value(JsDoc::from(
+        "Normal doc text\n@description Override description".to_string()
+      ))
+      .unwrap(),
+      json!({
+        "doc": "Override description",
+      })
+    );
+    // @description without preceding doc text
+    assert_eq!(
+      serde_json::to_value(JsDoc::from(
+        "@description The description".to_string()
+      ))
+      .unwrap(),
+      json!({
+        "doc": "The description",
+      })
+    );
+    // @description with other tags
+    assert_eq!(
+      serde_json::to_value(JsDoc::from(
+        "Normal doc\n@description Override\n@param {string} a a param"
+          .to_string()
+      ))
+      .unwrap(),
+      json!({
+        "doc": "Override",
+        "tags": [{
+          "kind": "param",
+          "name": "a",
+          "type": "string",
+          "doc": "a param",
+        }]
+      })
+    );
+    // multi-line @description
+    assert_eq!(
+      serde_json::to_value(JsDoc::from(
+        "@description Line 1\nLine 2".to_string()
+      ))
+      .unwrap(),
+      json!({
+        "doc": "Line 1\nLine 2",
+      })
+    );
   }
 
   #[test]
@@ -1208,6 +1300,16 @@ multi-line
         "type": "Map<string, string>",
       })
     );
+    assert_eq!(
+      serde_json::to_value(JsDocTag::Summary {
+        doc: "A brief summary".into(),
+      })
+      .unwrap(),
+      json!({
+        "kind": "summary",
+        "doc": "A brief summary",
+      })
+    );
     assert_eq!(
       serde_json::to_value(JsDocTag::Unsupported {
         value: "unsupported".into()

src/printer.rs

@@ -406,6 +406,10 @@ impl DocPrinter<'_> {
         writeln!(w, "{}@{}", Indent(indent), colors::magenta("since"))?;
         self.format_jsdoc_tag_doc(w, doc, indent)
       }
+      JsDocTag::Summary { doc } => {
+        writeln!(w, "{}@{}", Indent(indent), colors::magenta("summary"))?;
+        self.format_jsdoc_tag_doc(w, doc, indent)
+      }
       JsDocTag::Priority { priority } => {
         writeln!(
           w,

tests/snapshots/html_test__html_doc_files_multiple-21.snap

@@ -121,7 +121,8 @@ expression: files.get(file_name).unwrap()
         <div>
           <div class="text-2xl leading-none break-all">
             <span class="text-Enum">enum</span>&nbsp;<span class="font-bold">Enum2</span>
-          </div></div></div><div><div class="space-y-7" id=""><section class="section"  id="members"><div>
+          </div></div></div><div><div class="space-y-7" id=""><div class="markdown"><p>the description</p>
+</div><section class="section"  id="members"><div>
       <h2 class="anchorable mb-1"><a href="#members" class="anchor" aria-label="Anchor" tabIndex="-1"><svg
   width="16"
   height="16"

tests/snapshots/html_test__html_doc_files_multiple-73.snap

@@ -214,7 +214,8 @@ Enums</h2></div><div class="namespaceSection"><div id="namespace_enum" class="na
     </div><div id="namespace_enum2" class="namespaceItem" ><div class="docNodeKindIcon"><div class="text-Enum bg-Enum/15 dark:text-EnumDark dark:bg-EnumDark/15" title="Enum">E</div></div>
 <div class="namespaceItemContent">
 		    <a href=".&#x2F;.&#x2F;.&#x2F;~&#x2F;Enum2.html" title="Enum2">
-			    <span>Enum2</span></a></div>
+			    <span>Enum2</span></a><div class="namespaceItemContentDoc"><div class="markdown"><p>the summary</p>
+</div></div></div>
     </div></div>
 </section>
 <section class="section"  id="default_functions"><div>

tests/snapshots/html_test__html_doc_files_multiple.snap

@@ -1232,7 +1232,7 @@ expression: files
               "kind": "other",
               "value": {
                 "id": "",
-                "docs": null,
+                "docs": "<div class=\"markdown\"><p>the description</p>\n</div>",
                 "sections": [
                   {
                     "header": {

tests/snapshots/html_test__symbol_group.snap

@@ -231,7 +231,7 @@ expression: search_index
       ],
       "name": "Enum2",
       "file": ".",
-      "doc": "",
+      "doc": "the description",
       "url": "././~/Enum2.html",
       "deprecated": false
     },

tests/snapshots/html_test__symbol_search.snap

@@ -203,6 +203,11 @@ export enum Enum {
   Bar = "bar",
 }
 
+/**
+ * description to be overwritten
+ * @summary the summary
+ * @description the description
+ */
 export enum Enum2 {
   Foo,
   Bar,