use getJsDocMetadata by default and fallback to symbol

souporserious · Jun 12, 2024 · 8a590ab · 8a590ab
1 parent 9675822
commit 8a590ab
Show file tree

Hide file tree

Showing 2 changed files with 38 additions and 22 deletions.
diff --git a/packages/utils/src/types/getTypeDocumentation.test.ts b/packages/utils/src/types/getTypeDocumentation.test.ts
@@ -60,6 +60,7 @@ describe('getTypeDocumentation', () => {
                 "description": "Provides the initial count.",
                 "name": "initialCount",
                 "required": false,
+                "tags": undefined,
                 "type": "number",
               },
             ],
@@ -805,8 +806,7 @@ describe('getTypeDocumentation', () => {
       {
         "accessors": [
           {
-            "description": "Increments the count.
-      Returns the current count.",
+            "description": "Increments the count.",
             "modifier": "setter",
             "name": "accessorCount",
             "parameters": [
@@ -820,16 +820,17 @@ describe('getTypeDocumentation', () => {
             ],
             "returnType": "number",
             "scope": undefined,
+            "tags": undefined,
             "type": "number",
             "visibility": undefined,
           },
           {
-            "description": "Increments the count.
-      Returns the current count.",
+            "description": "Returns the current count.",
             "modifier": "getter",
             "name": "accessorCount",
             "returnType": "number",
             "scope": undefined,
+            "tags": undefined,
             "type": "number",
             "visibility": undefined,
           },
@@ -856,6 +857,7 @@ describe('getTypeDocumentation', () => {
             "parameters": [],
             "returnType": "void",
             "scope": undefined,
+            "tags": undefined,
             "type": "() => void",
             "visibility": undefined,
           },
@@ -866,6 +868,7 @@ describe('getTypeDocumentation', () => {
             "parameters": [],
             "returnType": "void",
             "scope": undefined,
+            "tags": undefined,
             "type": "() => void",
             "visibility": undefined,
           },
@@ -884,11 +887,11 @@ describe('getTypeDocumentation', () => {
             ],
             "returnType": "number",
             "scope": undefined,
+            "tags": undefined,
             "type": "(isFloored?: boolean) => number",
             "visibility": "public",
           },
           {
-            "description": undefined,
             "modifier": undefined,
             "name": "getStaticCount",
             "parameters": [],
@@ -901,15 +904,13 @@ describe('getTypeDocumentation', () => {
         "name": "Counter",
         "properties": [
           {
-            "description": undefined,
             "isReadonly": false,
             "name": "initialCount",
             "scope": undefined,
             "type": "number",
             "visibility": undefined,
           },
           {
-            "description": undefined,
             "isReadonly": false,
             "name": "staticCount",
             "scope": "static",

diff --git a/packages/utils/src/types/getTypeDocumentation.ts b/packages/utils/src/types/getTypeDocumentation.ts
@@ -25,6 +25,17 @@ import {
   getSymbolDescription,
 } from '../index'
 
+export interface PropertyMetadata {
+  name?: string
+  description?: string
+  tags?: { tagName: string; text?: string }[]
+  defaultValue?: any
+  required: boolean
+  type: string
+  properties?: PropertyMetadata[]
+  unionProperties?: PropertyMetadata[][]
+}
+
 /** Analyzes metadata from interfaces, type aliases, classes, functions, and variable declarations. */
 export function getTypeDocumentation(
   declaration:
@@ -323,13 +334,13 @@ function processClassAccessor(
     ...(isSetter ? { parameters } : {}),
     returnType,
     name: accessor.getName(),
-    description: getSymbolDescription(accessor.getSymbolOrThrow()),
     modifier: getModifier(accessor),
     scope: getScope(accessor),
     visibility: getVisibility(accessor),
     type: accessor
       .getType()
       .getText(accessor, TypeFormatFlags.UseAliasDefinedOutsideCurrentScope),
+    ...getJsDocMetadata(accessor),
   }
 }
 
@@ -354,7 +365,6 @@ function processClassMethod(
   return {
     parameters,
     name: method.getName(),
-    description: getSymbolDescription(method.getSymbolOrThrow()),
     modifier: getModifier(method),
     scope: getScope(method),
     visibility: getVisibility(method),
@@ -364,20 +374,21 @@ function processClassMethod(
     returnType: signature
       .getReturnType()
       .getText(method, TypeFormatFlags.UseAliasDefinedOutsideCurrentScope),
+    ...getJsDocMetadata(method),
   }
 }
 
 /** Processes a class property declaration into a metadata object. */
 function processClassPropertyDeclaration(property: PropertyDeclaration) {
   return {
     name: property.getName(),
-    description: getSymbolDescription(property.getSymbolOrThrow()),
     scope: getScope(property),
     visibility: getVisibility(property),
     isReadonly: property.isReadonly(),
     type: property
       .getType()
       .getText(property, TypeFormatFlags.UseAliasDefinedOutsideCurrentScope),
+    ...getJsDocMetadata(property),
   }
 }
 
@@ -404,12 +415,18 @@ function processParameterType(
   } = {
     defaultValue,
     name: isObjectBindingPattern ? undefined : parameterDeclaration.getName(),
-    description: getSymbolDescription(parameterDeclaration.getSymbolOrThrow()),
     required: !parameterDeclaration.hasQuestionToken() && !defaultValue,
     type: parameterType.getText(
       enclosingNode,
       TypeFormatFlags.UseAliasDefinedOutsideCurrentScope
     ),
+    ...getJsDocMetadata(parameterDeclaration),
+  }
+
+  if (!metadata.description) {
+    metadata.description = getSymbolDescription(
+      parameterDeclaration.getSymbolOrThrow()
+    )
   }
 
   const typeDeclaration = parameterType.getSymbol()?.getDeclarations()?.at(0)
@@ -461,16 +478,6 @@ function processParameterType(
   return metadata
 }
 
-export interface PropertyMetadata {
-  name?: string
-  description?: string
-  defaultValue?: any
-  required: boolean
-  type: string
-  properties?: (PropertyMetadata | null)[]
-  unionProperties?: PropertyMetadata[][]
-}
-
 /** Processes union types into an array of property arrays. */
 function processUnionType(
   unionType: Type<ts.UnionType>,
@@ -634,11 +641,19 @@ function processProperty(
   const propertyMetadata: PropertyMetadata = {
     defaultValue,
     name: propertyName,
-    description: getSymbolDescription(property),
     required: !property.isOptional() && defaultValue === undefined,
     type: typeText,
   }
 
+  const jsDocMetadata = declaration ? getJsDocMetadata(declaration) : undefined
+
+  if (jsDocMetadata) {
+    propertyMetadata.description = jsDocMetadata.description
+    propertyMetadata.tags = jsDocMetadata.tags
+  } else {
+    propertyMetadata.description = getSymbolDescription(property)
+  }
+
   if (propertyType.isObject()) {
     const typeDeclaration = propertyType.getSymbol()?.getDeclarations()?.at(0)
     const isLocalType = typeDeclaration