Reattach default-export doc comments

Summary:
**Context**

Strict TypeScript API readiness: High quality inline docs should reach users via TypeScript in their IDEs.

**This diff**

Prior iterations of our Flow → TS translation stack dropped doc comments for default-exported values, and/or identifiers which change shape after type transformation (e.g. Flow `component` syntax), meaning many root APIs (`View`, `ScrollView`, `Pressable`, and others) showed no documentation on hover.

This diff extends the existing `reattachDocComments` transform to handle doc comment repositioning (suitable for the TS lang server) from a greater set of source positions:

- the exported declaration
- a `.displayName` assignment
- a HOC-wrapped inner component
- a renamed wrapper's public-named component
- a `declare const` / `declare export default typeof X` stub

**Impact**

(With the source code JSDoc improvements earlier in this stack.)

| Before (legacy types) | After (Strict API) |
| -- |
|  {F1991869487}  | {F1991869472}  |
| ⚠️ No inline docs for many symbols | ✅ New, detailed inline docs reach the TS server 🎉 |

Changelog:  
[General][Fixed] - Preserve doc comments on root API symbols in the generated TypeScript types

Differential Revision: D109316361

Author: huntie

scripts/js-api/build-types/transforms/flow/__tests__/reattachDocComments-test.js

@@ -19,6 +19,17 @@ async function translate(code: string): Promise<string> {
   return print(result.ast, result.mutatedCode, prettierOptions);
 }
 
+/**
+ * Assert that `marker` appears exactly once (moved, not duplicated) and is the
+ * leading comment of the `export default` declaration.
+ */
+function expectDocOnDefaultExport(result: string, marker: string): void {
+  expect(result.split(marker).length - 1).toBe(1);
+  expect(result).toMatch(
+    new RegExp(`/\\*\\*[\\s\\S]*?${marker}[\\s\\S]*?\\*/\\s*export default`),
+  );
+}
+
 describe('reattachDocComments', () => {
   test('should move component doc block', async () => {
     const code = `
@@ -53,6 +64,7 @@ describe('reattachDocComments', () => {
       "
     `);
   });
+
   test('should move variable doc block', async () => {
     const code = `
         const bar = 'bar';
@@ -83,4 +95,156 @@ describe('reattachDocComments', () => {
       "
     `);
   });
+
+  test('should move doc block from a `component` declaration', async () => {
+    const code = `
+        import * as React from 'react';
+
+        /**
+         * Foo documentation
+         */
+        component Foo(...props: FooProps) {
+          return null;
+        }
+
+        Foo.displayName = 'Foo';
+
+        export default Foo;
+    `;
+    const result = await translate(code);
+    expectDocOnDefaultExport(result, 'Foo documentation');
+  });
+
+  test('should move doc block from a memo-wrapped component via its display name', async () => {
+    const code = `
+        import * as React from 'react';
+
+        /**
+         * Foo documentation
+         */
+        function Foo(props: FooProps) {
+          return null;
+        }
+
+        const MemoedFoo = memo(Foo);
+        MemoedFoo.displayName = 'Foo';
+
+        export default MemoedFoo;
+    `;
+    const result = await translate(code);
+    expectDocOnDefaultExport(result, 'Foo documentation');
+  });
+
+  test('should move doc block from the public (display) named declaration', async () => {
+    const code = `
+        import * as React from 'react';
+
+        /**
+         * Foo documentation
+         */
+        class Foo extends React.Component<FooProps> {}
+
+        const FooWrapper = (props: FooProps) => null;
+        FooWrapper.displayName = 'Foo';
+
+        export default FooWrapper;
+    `;
+    const result = await translate(code);
+    expectDocOnDefaultExport(result, 'Foo documentation');
+  });
+
+  test('should reattach through an `as` cast in the default export', async () => {
+    const code = `
+        import * as React from 'react';
+
+        /**
+         * Foo documentation
+         */
+        const Foo = (props: FooProps) => null;
+
+        export default Foo as FooType;
+    `;
+    const result = await translate(code);
+    expectDocOnDefaultExport(result, 'Foo documentation');
+  });
+
+  test('should leave the doc block on a directly class-exported declaration', async () => {
+    const code = `
+        import * as React from 'react';
+
+        /**
+         * Foo documentation
+         */
+        class Foo extends React.Component<FooProps> {}
+
+        export default Foo;
+    `;
+    const result = await translate(code);
+    // TypeScript resolves the doc on the class declaration; it must stay there
+    // and must not be moved onto the `export default` statement.
+    expect(result.split('Foo documentation').length - 1).toBe(1);
+    expect(result).toMatch(/\*\/\s*class Foo/);
+    expect(result).not.toMatch(/\*\/\s*export default/);
+  });
+
+  test('should move doc block from a `declare const` (.js.flow stub)', async () => {
+    const code = `
+        'use strict';
+
+        /**
+         * Foo documentation
+         */
+        declare const Foo: {bar(): void};
+
+        export default Foo;
+    `;
+    const result = await translate(code);
+    expectDocOnDefaultExport(result, 'Foo documentation');
+  });
+
+  test('should reattach for `declare export default typeof Foo`', async () => {
+    const code = `
+        'use strict';
+
+        /**
+         * Foo documentation
+         */
+        declare const Foo: {bar(): void};
+
+        declare export default typeof Foo;
+    `;
+    const result = await translate(code);
+    expect(result.split('Foo documentation').length - 1).toBe(1);
+    expect(result).toMatch(
+      /\/\*\*[\s\S]*?Foo documentation[\s\S]*?\*\/\s*declare export default/,
+    );
+  });
+
+  test('should not duplicate a doc block already on the default export', async () => {
+    const code = `
+        const Foo = (props: FooProps) => null;
+
+        /**
+         * Foo documentation
+         */
+        export default Foo;
+    `;
+    const result = await translate(code);
+    expectDocOnDefaultExport(result, 'Foo documentation');
+  });
+
+  test('should ignore build directive comments', async () => {
+    const code = `
+        import * as React from 'react';
+
+        /** @build-types emit-as-interface */
+        const Foo = (props: FooProps) => null;
+
+        export default Foo;
+    `;
+    const result = await translate(code);
+    // The directive must not be moved onto (or left as a leading comment of)
+    // the default export.
+    expect(result).not.toMatch(/\*\/\s*export default/);
+  });
 });