merge signatures

Author: avivkeller

src/generators/jsx-ast/utils/buildContent.mjs

@@ -37,13 +37,10 @@ const createChangeElement = entry => {
     // Process lifecycle changes (added, deprecated, etc.)
     ...Object.entries(LIFECYCLE_LABELS)
       .filter(([field]) => entry[field])
-      .map(([field, label]) => {
-        const versions = enforceArray(entry[field]);
-        return {
-          versions,
-          label: `${label}: ${versions.join(', ')}`,
-        };
-      }),
+      .map(([field, label]) => ({
+        versions: enforceArray(entry[field]),
+        label: `${label}: ${enforceArray(entry[field]).join(', ')}`,
+      })),
 
     // Process explicit changes if they exist
     ...(entry.changes?.map(change => ({
@@ -53,7 +50,7 @@ const createChangeElement = entry => {
     })) || []),
   ];
 
-  if (changeEntries.length === 0) {
+  if (!changeEntries.length) {
     return null;
   }
 
@@ -69,20 +66,17 @@ const createChangeElement = entry => {
  * @param {string|undefined} sourceLink - The source link path
  * @returns {import('hastscript').Element|null} The source link element or null if no source link
  */
-const createSourceLink = sourceLink => {
-  if (!sourceLink) {
-    return null;
-  }
-
-  return createElement('span', [
-    INTERNATIONALIZABLE.sourceCode,
-    createElement(
-      'a',
-      { href: `${DOC_NODE_BLOB_BASE_URL}${sourceLink}` },
-      sourceLink
-    ),
-  ]);
-};
+const createSourceLink = sourceLink =>
+  sourceLink
+    ? createElement('span', [
+        INTERNATIONALIZABLE.sourceCode,
+        createElement(
+          'a',
+          { href: `${DOC_NODE_BLOB_BASE_URL}${sourceLink}` },
+          sourceLink
+        ),
+      ])
+    : null;
 
 /**
  * Creates a heading element with appropriate styling and metadata
@@ -102,30 +96,25 @@ const createHeadingElement = (content, changeElement) => {
         { trimWhitespace: true }
       ).children;
 
-  const headingChildren = [
-    createElement('div', [
-      createElement(`h${depth}`, [
-        createElement(`a#${slug}`, { href: `#${slug}` }, headingContent),
-      ]),
+  const headingWrapper = createElement('div', [
+    createElement(`h${depth}`, [
+      createElement(`a#${slug}`, { href: `#${slug}` }, headingContent),
     ]),
-  ];
+  ]);
 
   // Add type icon if available
   if (type && type !== 'misc') {
-    headingChildren[0].children.unshift(
-      createJSXElement(JSX_IMPORTS.DataTag.name, {
-        kind: type,
-        size: 'sm',
-      })
+    headingWrapper.children.unshift(
+      createJSXElement(JSX_IMPORTS.DataTag.name, { kind: type, size: 'sm' })
     );
   }
 
   // Add change history if available
   if (changeElement) {
-    headingChildren[0].children.push(changeElement);
+    headingWrapper.children.push(changeElement);
   }
 
-  return createElement('div', headingChildren);
+  return headingWrapper;
 };
 
 /**
@@ -159,10 +148,11 @@ const transformStabilityNode = (node, index, parent) => {
  * @returns {[typeof SKIP]} Visitor instruction to skip the node
  */
 const transformHeadingNode = (entry, node, index, parent) => {
-  const changeElement = createChangeElement(entry);
-
   // Replace node with new heading and anchor
-  parent.children[index] = createHeadingElement(node, changeElement);
+  parent.children[index] = createHeadingElement(
+    node,
+    createChangeElement(entry)
+  );
 
   // Add source link if available
   const sourceLink = createSourceLink(entry.source_link);
@@ -172,11 +162,7 @@ const transformHeadingNode = (entry, node, index, parent) => {
 
   // Add method signatures for appropriate types
   if (TYPES_WITH_METHOD_SIGNATURES.includes(node.data.type)) {
-    parent.children.splice(
-      index + (sourceLink ? 2 : 1),
-      1,
-      ...createSignatureElements(entry)
-    );
+    createSignatureElements(parent, node.data.entries || [entry]);
   }
 
   return [SKIP];
@@ -222,6 +208,62 @@ const createDocumentLayout = (entries, sideBarProps, metaBarProps) => {
   ]);
 };
 
+/**
+ * Identifies and removes duplicate headings across metadata entries while tracking them
+ * @param {Array<ApiDocMetadataEntry>} metadataEntries - API documentation metadata entries
+ * @returns {Array<ApiDocMetadataEntry>} Processed entries with duplicates removed
+ */
+const removeDuplicates = metadataEntries => {
+  // Group entries by their heading's full name
+  const entriesByName = {};
+
+  // First pass: identify headings with method signatures
+  metadataEntries.forEach(entry => {
+    visit(entry.content, createQueries.UNIST.isHeading, node => {
+      if (TYPES_WITH_METHOD_SIGNATURES.includes(node.data.type)) {
+        const fullName = getFullName(node.data);
+        (entriesByName[fullName] ??= []).push({ entry, node });
+      }
+    });
+  });
+
+  // Second pass: remove duplicates, keeping only the last occurrence
+  for (const matches of Object.values(entriesByName)) {
+    if (matches.length > 1) {
+      // Get the last match which will be kept
+      const lastMatch = matches[matches.length - 1];
+
+      // Add all entries to the last entry's node data
+      lastMatch.node.data.entries = matches.map(match => match.entry);
+
+      // Remove all but the last duplicate from their parent nodes
+      matches.slice(0, -1).forEach(match => {
+        const { entry, node } = match;
+
+        // Find the parent of the node to remove
+        visit(entry.content, parent => {
+          // Check if this parent contains our node
+          const index = (parent.children || []).indexOf(node);
+          if (index !== -1) {
+            // Remove the node from its parent's children
+            parent.children.splice(index, 1);
+            return true; // Stop traversal once found and removed
+          }
+          return false;
+        });
+      });
+    }
+  }
+
+  // Filter out any entries that are now empty after removal
+  return metadataEntries.filter(
+    entry =>
+      entry.content &&
+      entry.content.children &&
+      entry.content.children.length > 0
+  );
+};
+
 /**
  * @typedef {import('estree').Node & { data: ApiDocMetadataEntry }} JSXContent
  *
@@ -233,9 +275,11 @@ const createDocumentLayout = (entries, sideBarProps, metaBarProps) => {
  * @returns {JSXContent} The processed MDX content
  */
 const buildContent = (metadataEntries, head, sideBarProps, remark) => {
-  const metaBarProps = buildMetaBarProps(head, metadataEntries);
+  const processedEntries = removeDuplicates(metadataEntries);
+  const metaBarProps = buildMetaBarProps(head, processedEntries);
+
   const root = createDocumentLayout(
-    metadataEntries,
+    processedEntries,
     sideBarProps,
     metaBarProps
   );

src/generators/jsx-ast/utils/createSignatureElements.mjs

@@ -129,7 +129,7 @@ const createPropertyTable = node => {
  */
 const generateSignatures = (functionName, signature) => {
   const { params, return: returnType } = signature;
-  const returnStr = returnType ? `: ${returnType.name}` : '';
+  const returnStr = returnType ? `: ${returnType.type}` : '';
 
   // Handle case with no optional parameters
   const optionalParams = params.filter(param => param.optional);
@@ -200,18 +200,43 @@ export const getFullName = ({ name, text }) => {
 };
 
 /**
- * Creates documentation from an API metadata entry
- * @param {ApiDocMetadataEntry} entry - API documentation metadata
+ * Creates documentation from API metadata entries
+ * @param {import('@types/mdast').Parent} parent - The parent node
+ * @param {ApiDocMetadataEntry[]} entries - Array of API documentation metadata entries
  */
-export default entry => {
-  const list = entry.content.children.find(isTypedList);
+export default (parent, entries) => {
+  // Find the list index in the parent for later replacement
+  const listIdx = parent.children.findIndex(isTypedList);
+  if (listIdx === -1) {
+    return;
+  }
+
+  // Create array for all elements from all entries
+  const elements = [];
 
-  const params = list ? list.children.map(parseListItem) : [];
-  const signature = parseSignature(entry.heading.data.text, params);
-  const displayName = getFullName(entry.heading.data);
+  // Process all entries
+  for (const entry of entries) {
+    // Find the list in the container
+    const list = entry.content.children.find(isTypedList);
 
-  const signatureCodeBlock = createSignatureCodeBlock(displayName, signature);
-  const propertyTable = list ? createPropertyTable(list) : null;
+    // Process the entry
+    const params = list ? list.children.map(parseListItem) : [];
+    const signature = parseSignature(entry.heading.data.text, params);
+    const displayName = getFullName(entry.heading.data);
 
-  return [signatureCodeBlock, propertyTable].filter(Boolean);
+    // Create signature code block
+    const signatureCodeBlock = createSignatureCodeBlock(displayName, signature);
+    if (signatureCodeBlock) elements.push(signatureCodeBlock);
+
+    // Create property table
+    if (list) {
+      const propertyTable = createPropertyTable(list);
+      elements.push(propertyTable);
+    }
+  }
+
+  // Replace the list in the parent with all collected elements
+  if (elements.length > 0) {
+    parent.children.splice(listIdx, 1, ...elements);
+  }
 };