@raycast/generate-docs - npm Package Compare versions

Comparing version 0.7.13 to 0.8.0

index.js

@@ -136,2 +136,11 @@ #!/usr/bin/env node
 
+    content = replaceFunctionParametersTables(
+      filepath,
+      content,
+      markdown,
+      utils,
+      idsMap,
+      namesMap
+    );
+
     // We can't output this warning otherwise GitBook is confused and lower some headers priorities!?
@@ -332,2 +341,58 @@ // see https://raycastcommunity.slack.com/archives/C01AC2X0GMN/p1652895559836489
 
+const parametersTableRegex =
+  /^<FunctionParametersTableFromJSDoc name="(.+)" \/>/gm;
+/** Replaces all instances of `<FunctionParametersTableFromJSDoc name="..." />` by a markdown table generated from the JS docs */
+function replaceFunctionParametersTables(
+  filepath,
+  content,
+  markdown,
+  utils,
+  idsMap,
+  namesMap
+) {
+  let newContent = content;
+
+  const tables = [...content.matchAll(parametersTableRegex)].map((x) => x[1]);
+
+  for (const name of tables) {
+    let fn = utils.findFunctionWithName(name);
+
+    if (!fn) {
+      console.log(JSON.stringify(namesMap.get(name), null, "  "));
+      throw new Error("Cannot find function " + name);
+    }
+
+    fn = utils.getParametersFromFunction(fn);
+
+    let typeParameters = fn.typeParameter || [];
+    if (fn.extendedTypes?.length && fn.extendedTypes[0].typeArguments) {
+      const extended = idsMap.get(fn.extendedTypes[0].id);
+      typeParameters.push(
+        ...extended.typeParameter.map((x, i) => ({
+          ...x,
+          type: fn.extendedTypes[0].typeArguments[i],
+        }))
+      );
+    }
+
+    const props = fn.parameters
+      .filter(
+        (prop) => !prop.comment?.tags?.some((t) => t.tag === "deprecated")
+      )
+      .map((prop) => [
+        prop.name,
+        utils.getPropTypeString(prop, typeParameters),
+        !prop.flags?.isOptional, // required
+        utils.getDescription(prop),
+      ]);
+
+    newContent = newContent.replace(
+      `<FunctionParametersTableFromJSDoc name="${name}" />`,
+      markdown.generateFunctionParametersTable(name, props)
+    );
+  }
+
+  return newContent;
+}
+
 function formatAnchor(anchor) {
@@ -334,0 +399,0 @@ if (!anchor) {

markdown.js

@@ -53,2 +53,16 @@ const path = require("path");
 
+  function generateFunctionParametersTable(functionName, params) {
+    return `| Name | Description | Type |
+| :--- | :--- | :--- |
+${params
+  .sort((a, b) => (a[2] ? (b[2] ? 0 : -1) : b[2] ? 1 : 0))
+  .map(
+    ([name, type, required, desc]) =>
+      `| ${name}${
+        required ? '<mark style="color:red;">*</mark>' : ""
+      } | ${replaceLinksInDescription(desc)} | ${formatTypeString(type)} |`
+  )
+  .join("\n")}`;
+  }
+
   function replaceLinksInDescription(desc) {
@@ -97,3 +111,7 @@ return desc.replaceAll(/{@link ([^}]+)}/g, (match, p1) => generateLink(p1));
 
-  return { generatePropsTable, generateInterfaceTable };
+  return {
+    generatePropsTable,
+    generateInterfaceTable,
+    generateFunctionParametersTable,
+  };
 };

package.json

 {
   "name": "@raycast/generate-docs",
-  "version": "0.7.13",
+  "version": "0.8.0",
   "description": "",
@@ -5,0 +5,0 @@ "main": "index.js",

utils.js

@@ -240,2 +240,14 @@ // @ts-check
 
+  function findFunctionWithName(name) {
+    const match = namesMap.get(name);
+    if (!match) {
+      throw new Error("cannot find " + name);
+    }
+    return match.find((x) => x.kindString === "Function");
+  }
+
+  function getParametersFromFunction(fn) {
+    return fn.signatures[0];
+  }
+
   function getDescription(item) {
@@ -271,2 +283,4 @@ let desc = item.comment?.shortText || item.comment?.text;
     getDescription,
+    findFunctionWithName,
+    getParametersFromFunction,
   };
@@ -273,0 +287,0 @@ };

No alert changes

Improved metrics

Total package byte prevSize

27780

increased by10.07%

Lines of code

834

increased by11.2%

No dependency changes