apply table to more than just methods, fix titles

Author: avivkeller

eslint.config.mjs

@@ -104,7 +104,7 @@ export default defineConfig([
         CLIENT: 'readonly',
         SERVER: 'readonly',
       },
-      ecmaVersion: 'latest'
+      ecmaVersion: 'latest',
     },
   },
 ]);

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

@@ -24,6 +24,7 @@ import {
   TYPES_WITH_METHOD_SIGNATURES,
 } from '../constants.mjs';
 import createSignatureElements, {
+  createPropertyTable,
   getFullName,
 } from './createSignatureElements.mjs';
 
@@ -87,14 +88,14 @@ const createSourceLink = sourceLink =>
 const createHeadingElement = (content, changeElement) => {
   const { type, depth, slug } = content.data;
 
-  const headingContent = TYPES_WITH_METHOD_SIGNATURES.includes(type)
-    ? createElement('code', getFullName(content.data))
-    : sliceMarkdown(
-        content,
-        (findTextPositions(content, ':')[0] ?? -1) + 1,
-        getTreeLength(content),
-        { trimWhitespace: true }
-      ).children;
+  const headingContent =
+    getFullName(content.data, false) ||
+    sliceMarkdown(
+      content,
+      (findTextPositions(content, ':')[0] ?? -1) + 1,
+      getTreeLength(content),
+      { trimWhitespace: true }
+    ).children;
 
   const headingWrapper = createElement('div', [
     createElement(`h${depth}`, [
@@ -161,13 +162,12 @@ const transformHeadingNode = (entry, node, index, parent) => {
   }
 
   // Add method signatures for appropriate types
-  if (TYPES_WITH_METHOD_SIGNATURES.includes(node.data.type)) {
-    createSignatureElements(
-      parent,
-      node.data.entries || [entry],
-      index + (sourceLink ? 2 : 1)
-    );
-  }
+  createSignatureElements(
+    parent,
+    node.data.entries || [entry],
+    index + (sourceLink ? 2 : 1),
+    TYPES_WITH_METHOD_SIGNATURES.includes(node.data.type)
+  );
 
   return [SKIP];
 };
@@ -186,6 +186,11 @@ const processEntry = entry => {
   visit(content, createQueries.UNIST.isHeading, (node, idx, parent) =>
     transformHeadingNode(entry, node, idx, parent)
   );
+  visit(
+    content,
+    createQueries.UNIST.isTypedList,
+    (node, idx, parent) => (parent.children[idx] = createPropertyTable(node))
+  );
 
   return content;
 };

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

@@ -1,6 +1,6 @@
 import { h as createElement } from 'hastscript';
 
-import { isTypedList } from '../../../utils/generators.mjs';
+import createQueries from '../../../utils/queries/index.mjs';
 import { parseListItem } from '../../legacy-json/utils/parseList.mjs';
 import parseSignature from '../../legacy-json/utils/parseSignature.mjs';
 
@@ -70,10 +70,13 @@ export const processListItemsIntoProperties = (items, prefix = '') => {
     let description = [];
 
     // Special handling for "Returns: " nodes with a description, and no type
-    if (propName.startsWith('Returns: ') && propName.length > 9) {
+    if (
+      (propName.startsWith('Returns: ') || propName.startsWith('Returns ')) &&
+      propName.length > 9
+    ) {
       description = propName.substring(9).trim();
-      propName = 'Returns';
-      displayName = { ...propNode, value: 'Returns' };
+      propName = 'Returns:';
+      displayName = { ...propNode, value: propName };
     } else {
       const extracted = extractTypesAndDescription(paragraph.children.slice(1));
       types = extracted.types;
@@ -106,7 +109,7 @@ export const processListItemsIntoProperties = (items, prefix = '') => {
     });
 
     // Process nested properties
-    const nestedList = nestedContent.find(isTypedList);
+    const nestedList = nestedContent.find(createQueries.UNIST.isTypedList);
     if (nestedList) {
       const nestedProperties = processListItemsIntoProperties(
         nestedList.children,
@@ -228,37 +231,48 @@ export const createSignatureCodeBlock = (functionName, signature) => {
 /**
  * Gets the full name of a function.
  * @param {HeadingMetadataEntry} heading
+ * @param {any} fallback
  */
-export const getFullName = ({ name, text }) => {
-  const code = text.match(/`([^`]+)`/)?.[1];
+export const getFullName = ({ name, text }, fallback = name) => {
+  // Exit early if the name wasn't processed
+  if (name === text) {
+    return fallback;
+  }
+
+  const code = text.trim().match(/`([^`]+)`/)?.[1];
   return code?.includes(name)
-    ? code.slice(0, code.indexOf(name) + name.length)
-    : name;
+    ? code
+        .slice(0, code.indexOf(name) + name.length)
+        .replace(/^["']|new\s*/, '')
+    : fallback;
 };
 
 /**
  * Creates documentation from API metadata entries
  * @param {import('@types/mdast').Parent} parent - The parent node
  * @param {ApiDocMetadataEntry[]} entries - Array of API documentation metadata entries
  * @param {number} backupIndex - If there isn't a list, use this index
+ * @param {boolean} addSignatureCodebox - Is this a method?
  */
-export default (parent, entries, backupIndex) => {
+export default (parent, entries, backupIndex, addSignatureCodebox) => {
   // Find the list index in the parent for later replacement
-  const listIdx = parent.children.findIndex(isTypedList);
+  const listIdx = parent.children.findIndex(createQueries.UNIST.isTypedList);
   const elements = [];
 
   // Process all entries
   for (const entry of entries) {
     // Find the list in the container
-    const list = entry.content.children.find(isTypedList);
+    const list = entry.content.children.find(createQueries.UNIST.isTypedList);
 
-    // Process the entry
-    const params = list ? list.children.map(parseListItem) : [];
-    const signature = parseSignature(entry.heading.data.text, params);
-    const displayName = getFullName(entry.heading.data);
+    // Create a signature code box, if this is a method/ctor.
+    if (addSignatureCodebox) {
+      const params = list ? list.children.map(parseListItem) : [];
 
-    // Create signature code block
-    elements.push(createSignatureCodeBlock(displayName, signature));
+      const signature = parseSignature(entry.heading.data.text, params);
+      const displayName = getFullName(entry.heading.data);
+
+      elements.push(createSignatureCodeBlock(displayName, signature));
+    }
 
     // Create property table if a list exists
     if (list) {

src/generators/legacy-json/utils/parseList.mjs

@@ -6,7 +6,7 @@ import {
   TYPE_EXPRESSION,
 } from '../constants.mjs';
 import parseSignature from './parseSignature.mjs';
-import { isTypedList } from '../../../utils/generators.mjs';
+import createQueries from '../../../utils/queries/index.mjs';
 import { transformNodesToString } from '../../../utils/unist.mjs';
 
 /**
@@ -47,7 +47,7 @@ export const extractPattern = (text, pattern, key, current) => {
 export function parseListItem(child) {
   const current = {};
 
-  const subList = child.children.find(isTypedList);
+  const subList = child.children.find(createQueries.UNIST.isTypedList);
 
   // Extract and clean raw text from the node, excluding nested lists
   current.textRaw = transformTypeReferences(

src/utils/generators.mjs

@@ -96,29 +96,3 @@ export const sortChanges = (changes, key = 'version') => {
     return compare(coerceSemVer(aVersion), coerceSemVer(bVersion));
   });
 };
-
-/**
- * Determines if the input List node is a typed list
- * @param {import('@types/mdast').List} list
- */
-export const isTypedList = list => {
-  if (list.type !== 'list') {
-    // Exit early if not a list
-    return false;
-  }
-
-  const children = list?.children?.[0]?.children?.[0]?.children;
-
-  return (
-    // The first element must be a code block
-    children?.[0]?.type === 'inlineCode'
-      ? // Followed by a space
-        children?.[1]?.value.trim() === '' &&
-          // Followed by a link (type)
-          children?.[2]?.type === 'link' &&
-          // Types start with `<`
-          children?.[2]?.children?.[0]?.value?.[0] === '<'
-      : // Or a "Returns:"
-        children?.[0]?.value?.trim() === 'Returns:'
-  );
-};

src/utils/queries/index.mjs

@@ -241,6 +241,33 @@ createQueries.UNIST = {
    */
   isLinkReference: ({ type, identifier }) =>
     type === 'linkReference' && !!identifier,
+
+  /**
+   * @param {import('@types/mdast').List} list
+   * @returns {boolean}
+   */
+  isTypedList: list => {
+    if (list.type !== 'list') {
+      // Exit early if not a list
+      return false;
+    }
+
+    const children = list?.children?.[0]?.children?.[0]?.children;
+
+    return (
+      // The first element must be a code block
+      children?.[0]?.type === 'inlineCode'
+        ? // Followed by a space
+          children?.[1]?.value.trim() === '' &&
+            // Followed by a link (type)
+            children?.[2]?.type === 'link' &&
+            // Types start with `<`
+            children?.[2]?.children?.[0]?.value?.[0] === '<'
+        : // Or a "Returns:" / "Returns" (Malformed)
+          children?.[0]?.value?.trim() === 'Returns:' ||
+            children?.[0]?.value?.trim() === 'Returns'
+    );
+  },
 };
 
 export default createQueries;