read dockblock from nested flow object types (#810)

reactjs · Jun 23, 2023 · ddf4e20 · ddf4e20
1 parent 2d8dac0
commit ddf4e20
Show file tree

Hide file tree

Showing 4 changed files with 101 additions and 15 deletions.
diff --git a/.changeset/short-squids-knock.md b/.changeset/short-squids-knock.md
@@ -0,0 +1,5 @@
+---
+'react-docgen': patch
+---
+
+Read docblock in nested flow object types and use them as descriptions
diff --git a/packages/react-docgen/src/utils/__tests__/__snapshots__/getFlowType-test.ts.snap b/packages/react-docgen/src/utils/__tests__/__snapshots__/getFlowType-test.ts.snap
@@ -1,5 +1,65 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
+exports[`getFlowType > detects object types with descriptions 1`] = `
+{
+  "name": "signature",
+  "raw": "{
+  /** A */
+  a: string,
+  /** B */
+  b?: xyz
+}",
+  "signature": {
+    "properties": [
+      {
+        "description": "A",
+        "key": "a",
+        "value": {
+          "name": "string",
+          "required": true,
+        },
+      },
+      {
+        "description": "B",
+        "key": "b",
+        "value": {
+          "name": "xyz",
+          "required": false,
+        },
+      },
+    ],
+  },
+  "type": "object",
+}
+`;
+
+exports[`getFlowType > detects object types with maybe type 1`] = `
+{
+  "name": "signature",
+  "raw": "{ a: string, b: ?xyz }",
+  "signature": {
+    "properties": [
+      {
+        "key": "a",
+        "value": {
+          "name": "string",
+          "required": true,
+        },
+      },
+      {
+        "key": "b",
+        "value": {
+          "name": "xyz",
+          "nullable": true,
+          "required": true,
+        },
+      },
+    ],
+  },
+  "type": "object",
+}
+`;
+
 exports[`getFlowType > handles ObjectTypeSpreadProperty 1`] = `
 {
   "name": "signature",

diff --git a/packages/react-docgen/src/utils/__tests__/getFlowType-test.ts b/packages/react-docgen/src/utils/__tests__/getFlowType-test.ts
@@ -433,23 +433,29 @@ describe('getFlowType', () => {
     });
   });
 
+  test('detects object types with descriptions', () => {
+    const typePath = parse
+      .expression<TypeCastExpression>(
+        `x: {
+           /** A */
+           a: string,
+           /** B */
+           b?: xyz
+         }`,
+      )
+      .get('typeAnnotation')
+      .get('typeAnnotation');
+
+    expect(getFlowType(typePath)).toMatchSnapshot();
+  });
+
   test('detects object types with maybe type', () => {
     const typePath = parse
       .expression<TypeCastExpression>('x: { a: string, b: ?xyz }')
       .get('typeAnnotation')
       .get('typeAnnotation');
 
-    expect(getFlowType(typePath)).toEqual({
-      name: 'signature',
-      type: 'object',
-      signature: {
-        properties: [
-          { key: 'a', value: { name: 'string', required: true } },
-          { key: 'b', value: { name: 'xyz', nullable: true, required: true } },
-        ],
-      },
-      raw: '{ a: string, b: ?xyz }',
-    });
+    expect(getFlowType(typePath)).toMatchSnapshot();
   });
 
   test('resolves imported types used for objects', () => {

diff --git a/packages/react-docgen/src/utils/getFlowType.ts b/packages/react-docgen/src/utils/getFlowType.ts
@@ -32,6 +32,7 @@ import type {
   TypeParameterDeclaration,
   UnionTypeAnnotation,
 } from '@babel/types';
+import { getDocblock } from './docblock.js';
 
 const flowTypes: Record<string, string> = {
   AnyTypeAnnotation: 'any',
@@ -239,20 +240,34 @@ function handleObjectTypeAnnotation(
 
   if (Array.isArray(indexers)) {
     indexers.forEach((param) => {
-      type.signature.properties.push({
+      const typeDescriptor: (typeof type.signature.properties)[number] = {
         key: getFlowTypeWithResolvedTypes(param.get('key'), typeParams),
         value: getFlowTypeWithRequirements(param.get('value'), typeParams),
-      });
+      };
+      const docblock = getDocblock(param);
+
+      if (docblock) {
+        typeDescriptor.description = docblock;
+      }
+
+      type.signature.properties.push(typeDescriptor);
     });
   }
 
   path.get('properties').forEach((param) => {
     if (param.isObjectTypeProperty()) {
-      type.signature.properties.push({
+      const typeDescriptor: (typeof type.signature.properties)[number] = {
         // For ObjectTypeProperties `getPropertyName` always returns string
         key: getPropertyName(param) as string,
         value: getFlowTypeWithRequirements(param.get('value'), typeParams),
-      });
+      };
+      const docblock = getDocblock(param);
+
+      if (docblock) {
+        typeDescriptor.description = docblock;
+      }
+
+      type.signature.properties.push(typeDescriptor);
     } else if (param.isObjectTypeSpreadProperty()) {
       let spreadObject = resolveToValue(param.get('argument'));