feat: parse typescript types from jsdoc comments (#783)

Author: crowlKats

js/types.d.ts

@@ -329,36 +329,36 @@ export interface JsDocTagValued extends JsDocTagBase {
 
 export interface JsDocTagTyped extends JsDocTagBase {
   kind: "enum" | "extends" | "this" | "type";
-  type: string;
+  ts_type: TsTypeDef;
   doc?: string;
 }
 
 export interface JsDocTagNamedTyped extends JsDocTagBase {
   kind: "property" | "typedef";
   name: string;
-  type: string;
+  ts_type: TsTypeDef;
   doc?: string;
 }
 
 export interface JsDocTagParam extends JsDocTagBase {
   kind: "param";
   name: string;
-  type?: string;
+  ts_type?: TsTypeDef;
   optional?: true;
   default?: string;
   doc?: string;
 }
 
 export interface JsDocTagReturn extends JsDocTagBase {
   kind: "return";
-  type?: string;
+  ts_type?: TsTypeDef;
   doc?: string;
 }
 
 export interface JsDocTagThrows extends JsDocTagBase {
   kind: "throws";
-  type?: string;
-  doc: string;
+  ts_type?: TsTypeDef;
+  doc?: string;
 }
 
 export interface JsDocTagModule extends JsDocTagBase {

src/diff/js_doc.rs

@@ -106,10 +106,10 @@ fn tags_same_kind(a: &JsDocTag, b: &JsDocTag) -> bool {
     (Constructor, Constructor) => true,
     (Default { value: v1, .. }, Default { value: v2, .. }) => v1 == v2,
     (Deprecated { .. }, Deprecated { .. }) => true,
-    (Enum { type_ref: t1, .. }, Enum { type_ref: t2, .. }) => t1 == t2,
+    (Enum { ts_type: t1, .. }, Enum { ts_type: t2, .. }) => t1 == t2,
     (Example { .. }, Example { .. }) => true,
     (Experimental, Experimental) => true,
-    (Extends { type_ref: t1, .. }, Extends { type_ref: t2, .. }) => t1 == t2,
+    (Extends { ts_type: t1, .. }, Extends { ts_type: t2, .. }) => t1 == t2,
     (Ignore, Ignore) => true,
     (Internal, Internal) => true,
     (Module { .. }, Module { .. }) => true,
@@ -122,10 +122,10 @@ fn tags_same_kind(a: &JsDocTag, b: &JsDocTag) -> bool {
     (Return { .. }, Return { .. }) => true,
     (Tags { .. }, Tags { .. }) => true,
     (Template { name: n1, .. }, Template { name: n2, .. }) => n1 == n2,
-    (This { type_ref: t1, .. }, This { type_ref: t2, .. }) => t1 == t2,
-    (Throws { type_ref: t1, .. }, Throws { type_ref: t2, .. }) => t1 == t2,
+    (This { ts_type: t1, .. }, This { ts_type: t2, .. }) => t1 == t2,
+    (Throws { ts_type: t1, .. }, Throws { ts_type: t2, .. }) => t1 == t2,
     (TypeDef { name: n1, .. }, TypeDef { name: n2, .. }) => n1 == n2,
-    (TypeRef { type_ref: t1, .. }, TypeRef { type_ref: t2, .. }) => t1 == t2,
+    (TypeRef { ts_type: t1, .. }, TypeRef { ts_type: t2, .. }) => t1 == t2,
     (See { .. }, See { .. }) => true,
     (Since { .. }, Since { .. }) => true,
     (Priority { .. }, Priority { .. }) => true,

src/html/symbols/function.rs

@@ -12,6 +12,7 @@ use crate::html::types::type_params_summary;
 use crate::html::util::*;
 use crate::js_doc::JsDocTag;
 use crate::params::ParamPatternDef;
+use crate::ts_type::TsTypeDef;
 use indexmap::IndexSet;
 use serde::Deserialize;
 use serde::Serialize;
@@ -419,20 +420,20 @@ fn render_single_function(
     .tags
     .iter()
     .filter_map(|tag| {
-      if let JsDocTag::Throws { type_ref, doc } = tag
-        && (type_ref.is_some() || doc.is_some())
+      if let JsDocTag::Throws { ts_type, doc, .. } = tag
+        && (ts_type.is_some() || doc.is_some())
       {
-        return Some((type_ref, doc));
+        return Some((ts_type, doc));
       }
 
       None
     })
     .enumerate()
-    .map(|(i, (type_ref, doc))| {
+    .map(|(i, (ts_type, doc))| {
       render_function_throws(
         ctx,
         decl,
-        type_ref,
+        ts_type,
         doc,
         overload_id.clone(),
         i,
@@ -444,8 +445,8 @@ fn render_single_function(
   // Inject removed throws entries
   if let Some(td) = &throws_tags_diff {
     for removed_tag in &td.removed {
-      if let JsDocTag::Throws { type_ref, doc } = removed_tag
-        && (type_ref.is_some() || doc.is_some())
+      if let JsDocTag::Throws { ts_type, doc, .. } = removed_tag
+        && (ts_type.is_some() || doc.is_some())
       {
         let id = IdBuilder::new_with_parent(ctx, &overload_id)
           .kind(IdKind::Throws)
@@ -457,7 +458,10 @@ fn render_single_function(
           id,
           None,
           None,
-          type_ref.as_ref().map(|t| t.as_ref()).unwrap_or_default(),
+          ts_type
+            .as_ref()
+            .map(|t| t.repr.as_str())
+            .unwrap_or_default(),
           IndexSet::new(),
           doc.as_ref().map(|d| d.as_ref()),
           &decl.location,
@@ -660,38 +664,37 @@ fn inject_removed_params(
 fn render_function_throws(
   render_ctx: &RenderContext,
   decl: &Declaration,
-  type_ref: &Option<Box<str>>,
+  ts_type: &Option<TsTypeDef>,
   doc: &Option<Box<str>>,
   overload_id: Id,
   throws_id: usize,
   diff: &Option<crate::diff::TagsDiff>,
 ) -> DocEntryCtx {
-  let (diff_status, old_content) = if let Some(td) = diff {
-    if let Some(tag_diff) = td.modified.iter().find(|m| {
-      matches!(&m.new, JsDocTag::Throws { type_ref: t, .. } if t == type_ref)
+  let (diff_status, old_content) =
+    if let Some(td) = diff {
+      if let Some(tag_diff) = td.modified.iter().find(|m| {
+      matches!(&m.new, JsDocTag::Throws { ts_type: t, .. } if t == ts_type)
     }) {
       let old = if let JsDocTag::Throws {
-        type_ref: old_type_ref,
+        ts_type: old_ts_type,
         ..
       } = &tag_diff.old
       {
-        old_type_ref
-          .as_ref()
-          .map(|t| t.to_string())
+        old_ts_type.as_ref().map(|t| t.repr.clone())
       } else {
         None
       };
       (Some(DiffStatus::Modified), old)
     } else if td.added.iter().any(|a| {
-      matches!(a, JsDocTag::Throws { type_ref: t, .. } if t == type_ref)
+      matches!(a, JsDocTag::Throws { ts_type: t, .. } if t == ts_type)
     }) {
       (Some(DiffStatus::Added), None)
     } else {
       (None, None)
     }
-  } else {
-    (None, None)
-  };
+    } else {
+      (None, None)
+    };
 
   let id = IdBuilder::new_with_parent(render_ctx, &overload_id)
     .kind(IdKind::Throws)
@@ -703,9 +706,9 @@ fn render_function_throws(
     id,
     None,
     None,
-    type_ref
+    ts_type
       .as_ref()
-      .map(|doc| doc.as_ref())
+      .map(|t| t.repr.as_str())
       .unwrap_or_default(),
     IndexSet::new(),
     doc.as_ref().map(|doc| doc.as_ref()),

src/html/types.rs

@@ -459,6 +459,9 @@ pub(crate) fn render_type_def(
         html_escape::encode_text(&import_type.specifier),
       )
     }
+    TsTypeDefKind::Unsupported => {
+      html_escape::encode_text(&def.repr).into_owned()
+    }
   }
 }