[code-infra] Fix duplicate JSDoc in proptypes generation for merged declarations

The `getSymbolDocumentation` function was introduced in mui#47685 to handle
JSDoc merging across multiple TypeScript declarations. However, it
unconditionally joined all unique JSDoc comments when a symbol had
multiple declarations, which produced duplicated descriptions in the
generated propTypes for interface declaration merging and module
augmentation scenarios.

TypeScript treats JSDoc differently depending on how declarations
combine:

- Intersection types (type C = A & B): all constituent JSDoc are merged
- Interface extends (interface Z extends X, Y): first parent's JSDoc
wins
- Interface override (interface W extends X { prop }): the override's
JSDoc wins
- Declaration merging / module augmentation: last declaration's JSDoc
wins

The previous implementation treated all multi-declaration cases as
intersections, concatenating distinct comments. This caused issues in
downstream repos (e.g. mui-x) where module augmentation is used to
extend interface props — the original and augmented JSDoc would both
appear in the generated propTypes output.

The fix now uses `parentType.isIntersection()` to distinguish
intersection types (where merging is correct) from declaration merging
(where the last declaration should win), matching TypeScript's own
behavior.

Added test cases for all four JSDoc resolution scenarios:
- jsdoc-intersection: verifies both descriptions are merged
- jsdoc-interface-extends: verifies first parent's description wins
- jsdoc-interface-override: verifies override description wins
- declaration-merging: verifies last (augmented) description wins

Author: brijeshb42

packages-internal/scripts/typescript-to-proptypes/src/getPropTypesFromFile.ts

@@ -31,6 +31,7 @@ function getSymbolFileNames(symbol: ts.Symbol): Set<string> {
 function getSymbolDocumentation({
   symbol,
   project,
+  parentType,
 }: {
   symbol: ts.Symbol | undefined;
   project: TypeScriptProject;
@@ -42,23 +43,9 @@ function getSymbolDocumentation({
 
   const decl = symbol.getDeclarations();
   if (decl && decl.length > 0) {
-    // This behavior tries to replicate how TypeScript itself merges JSDoc comments
-    // It is a complex logic that changes based on the kind of declarations
-    // There is an open issue for it in: https://github.com/microsoft/TypeScript/issues/30901
-    //
-    // For intersection types (A & B), the symbol may have multiple declarations.
-    // We need to handle three cases:
-    // 1. Intersection (type C = A & B): merge JSDoc from all declarations (deduplicated)
-    // 2. Interface extends (interface Z extends X, Y): use the (only) declaration's JSDoc
-    // 3. Interface override (interface W extends X { prop }): use the override's JSDoc (which is the only declaration)
-    //
-    // Note: TypeScript gives us:
-    // - Multiple declarations for intersection types (one from each constituent type)
-    // - Single declaration for interface extends (from the original interface)
-    // - Single declaration for interface override (from the overriding interface)
-
-    // Get JSDoc comments paired with their declarations
-    const declarationsWithComments = decl
+    // Replicates how TypeScript merges JSDoc comments across declarations.
+    // See https://github.com/microsoft/TypeScript/issues/30901
+    const commentedDeclarations = decl
       .map((d) => {
         const jsDocNodes = ts.getJSDocCommentsAndTags(d).filter((node) => ts.isJSDoc(node));
         const comment =
@@ -67,19 +54,24 @@ function getSymbolDocumentation({
             : undefined;
         return { declaration: d, comment };
       })
-      .filter((item) => item.comment !== undefined);
+      .filter(
+        (item): item is { declaration: ts.Declaration; comment: string } =>
+          item.comment !== undefined,
+      );
+
+    if (commentedDeclarations.length > 0) {
+      if (commentedDeclarations.length === 1) {
+        return commentedDeclarations[0].comment;
+      }
 
-    if (declarationsWithComments.length > 0) {
-      // If there's only one declaration with a comment, use it
-      // This handles both interface extends and interface override cases
-      if (declarationsWithComments.length === 1) {
-        return declarationsWithComments[0].comment;
+      // Intersection types: merge unique JSDoc (matches TS hover behavior)
+      if (parentType && parentType.isIntersection()) {
+        const uniqueComments = [...new Set(commentedDeclarations.map((d) => d.comment))];
+        return uniqueComments.join('\n');
       }
 
-      // Multiple declarations with comments - this is the intersection case (type C = A & B)
-      // Merge JSDoc comments, deduplicating identical ones
-      const uniqueComments = [...new Set(declarationsWithComments.map((d) => d.comment))];
-      return uniqueComments.join('\n');
+      // Declaration merging / module augmentation: last declaration wins
+      return commentedDeclarations[commentedDeclarations.length - 1].comment;
     }
   }
 

packages-internal/scripts/typescript-to-proptypes/test/declaration-merging/input.tsx

@@ -0,0 +1,8 @@
+import * as React from 'react';
+import type { ComponentProps } from './types';
+
+export default function Component(props: ComponentProps) {
+  const { name, onItemClick } = props;
+
+  return <button onClick={(e) => onItemClick?.(e.nativeEvent)}>{name}</button>;
+}

packages-internal/scripts/typescript-to-proptypes/test/declaration-merging/output.js

@@ -0,0 +1,20 @@
+import * as React from 'react';
+import PropTypes from 'prop-types';
+function Component(props) {
+  const { name, onItemClick } = props;
+  return <button onClick={(e) => onItemClick?.(e.nativeEvent)}>{name}</button>;
+}
+
+Component.propTypes = {
+  /**
+   * A normal prop.
+   */
+  name: PropTypes.string.isRequired,
+  /**
+   * Augmented description of the callback.
+   * @param {MouseEvent | React.MouseEvent} event The event source (augmented).
+   */
+  onItemClick: PropTypes.func,
+};
+
+export default Component;

packages-internal/scripts/typescript-to-proptypes/test/declaration-merging/types.ts

@@ -0,0 +1,20 @@
+export interface ComponentProps {
+  /**
+   * Original description of the callback.
+   * @param {MouseEvent} event The event source.
+   */
+  onItemClick?(event: MouseEvent): void;
+  /**
+   * A normal prop.
+   */
+  name: string;
+}
+
+// Module augmentation / declaration merging
+export interface ComponentProps {
+  /**
+   * Augmented description of the callback.
+   * @param {MouseEvent | React.MouseEvent} event The event source (augmented).
+   */
+  onItemClick?(event: MouseEvent | React.MouseEvent): void;
+}

packages-internal/scripts/typescript-to-proptypes/test/jsdoc-interface-extends/input.tsx

@@ -0,0 +1,36 @@
+import * as React from 'react';
+
+interface BaseProps {
+  /**
+   * The label from base.
+   * @default 'base'
+   */
+  label: string;
+  /**
+   * If true, the component is disabled.
+   */
+  disabled?: boolean;
+}
+
+interface ExtraProps {
+  /**
+   * The label from extra.
+   * @default 'extra'
+   */
+  label: string;
+  /**
+   * The size of the component.
+   */
+  size?: 'small' | 'medium' | 'large';
+}
+
+interface CombinedProps extends BaseProps, ExtraProps {}
+
+export default function Component(props: CombinedProps) {
+  const { label, disabled, size } = props;
+  return (
+    <button disabled={disabled} data-size={size}>
+      {label}
+    </button>
+  );
+}

packages-internal/scripts/typescript-to-proptypes/test/jsdoc-interface-extends/output.js

@@ -0,0 +1,28 @@
+import * as React from 'react';
+import PropTypes from 'prop-types';
+function Component(props) {
+  const { label, disabled, size } = props;
+  return (
+    <button disabled={disabled} data-size={size}>
+      {label}
+    </button>
+  );
+}
+
+Component.propTypes = {
+  /**
+   * If true, the component is disabled.
+   */
+  disabled: PropTypes.bool,
+  /**
+   * The label from base.
+   * @default 'base'
+   */
+  label: PropTypes.string.isRequired,
+  /**
+   * The size of the component.
+   */
+  size: PropTypes.oneOf(['large', 'medium', 'small']),
+};
+
+export default Component;

packages-internal/scripts/typescript-to-proptypes/test/jsdoc-interface-override/input.tsx

@@ -0,0 +1,26 @@
+import * as React from 'react';
+
+interface BaseProps {
+  /**
+   * The label from base.
+   * @default 'base'
+   */
+  label: string;
+  /**
+   * If true, the component is disabled.
+   */
+  disabled?: boolean;
+}
+
+interface OverrideProps extends BaseProps {
+  /**
+   * The overridden label description.
+   * @default 'override'
+   */
+  label: string;
+}
+
+export default function Component(props: OverrideProps) {
+  const { label, disabled } = props;
+  return <button disabled={disabled}>{label}</button>;
+}

packages-internal/scripts/typescript-to-proptypes/test/jsdoc-interface-override/output.js

@@ -0,0 +1,20 @@
+import * as React from 'react';
+import PropTypes from 'prop-types';
+function Component(props) {
+  const { label, disabled } = props;
+  return <button disabled={disabled}>{label}</button>;
+}
+
+Component.propTypes = {
+  /**
+   * If true, the component is disabled.
+   */
+  disabled: PropTypes.bool,
+  /**
+   * The overridden label description.
+   * @default 'override'
+   */
+  label: PropTypes.string.isRequired,
+};
+
+export default Component;

packages-internal/scripts/typescript-to-proptypes/test/jsdoc-intersection/input.tsx

@@ -0,0 +1,36 @@
+import * as React from 'react';
+
+type BaseProps = {
+  /**
+   * The label of the component.
+   * @default 'base'
+   */
+  label: string;
+  /**
+   * If true, the component is disabled.
+   */
+  disabled?: boolean;
+};
+
+type ExtraProps = {
+  /**
+   * The label from extra props.
+   * @default 'extra'
+   */
+  label: string;
+  /**
+   * The size of the component.
+   */
+  size?: 'small' | 'medium' | 'large';
+};
+
+type CombinedProps = BaseProps & ExtraProps;
+
+export default function Component(props: CombinedProps) {
+  const { label, disabled, size } = props;
+  return (
+    <button disabled={disabled} data-size={size}>
+      {label}
+    </button>
+  );
+}

packages-internal/scripts/typescript-to-proptypes/test/jsdoc-intersection/output.js

@@ -0,0 +1,30 @@
+import * as React from 'react';
+import PropTypes from 'prop-types';
+function Component(props) {
+  const { label, disabled, size } = props;
+  return (
+    <button disabled={disabled} data-size={size}>
+      {label}
+    </button>
+  );
+}
+
+Component.propTypes = {
+  /**
+   * If true, the component is disabled.
+   */
+  disabled: PropTypes.bool,
+  /**
+   * The label of the component.
+   * @default 'base'
+   * The label from extra props.
+   * @default 'extra'
+   */
+  label: PropTypes.string.isRequired,
+  /**
+   * The size of the component.
+   */
+  size: PropTypes.oneOf(['large', 'medium', 'small']),
+};
+
+export default Component;