feat(code-gen/experimental): generate type docs strings as JSDoc blocks

This improves usage of tags like `@deprecated` on fields on `@link` tags to link to routes and other types.
compasjs · May 5, 2023 · a94ee51 · a94ee51
1 parent 53f03cd
commit a94ee51
Show file tree

Hide file tree

Showing 13 changed files with 492 additions and 187 deletions.
diff --git a/packages/code-gen/src/experimental/api-client/react-query.js b/packages/code-gen/src/experimental/api-client/react-query.js
@@ -7,7 +7,7 @@ import {
   fileContextRemoveLinePrefix,
   fileContextSetIndent,
 } from "../file/context.js";
-import { fileFormatInlineComment } from "../file/format.js";
+import { fileFormatInlineComment } from "../file/docs.js";
 import { fileWrite, fileWriteInline } from "../file/write.js";
 import { referenceUtilsGetProperty } from "../processors/reference-utils.js";
 import { structureResolveReference } from "../processors/structure.js";
@@ -497,6 +497,7 @@ export function reactQueryGenerateFunction(
   ${parameterListWithExtraction({
     prefix: "opts",
     withRequestConfig: true,
+    defaultToNull: false,
   })}
   );
   }, options);`,
@@ -550,6 +551,7 @@ ${hookName}.queryKey = (
   ${parameterListWithExtraction({
     prefix: "opts",
     withRequestConfig: true,
+    defaultToNull: false,
   })}
   ));
 }
@@ -572,6 +574,7 @@ ${hookName}.queryKey = (
      ${parameterListWithExtraction({
        prefix: "opts",
        withRequestConfig: true,
+       defaultToNull: false,
      })}
   ));
 }
@@ -675,6 +678,7 @@ ${hookName}.setQueryData = (
   ${parameterListWithExtraction({
     prefix: "variables",
     withRequestConfig: true,
+    defaultToNull: false,
   })}
 ), options);
 `,

diff --git a/packages/code-gen/src/experimental/crud/handlers.js b/packages/code-gen/src/experimental/crud/handlers.js
@@ -7,7 +7,7 @@ import {
   fileContextRemoveLinePrefix,
   fileContextSetIndent,
 } from "../file/context.js";
-import { fileFormatInlineComment } from "../file/format.js";
+import { fileFormatInlineComment } from "../file/docs.js";
 import { fileWrite } from "../file/write.js";
 import {
   crudInformationGetHasCustomReadableType,

diff --git a/packages/code-gen/src/experimental/database/js-postgres.js b/packages/code-gen/src/experimental/database/js-postgres.js
@@ -7,7 +7,7 @@ import {
   fileContextRemoveLinePrefix,
   fileContextSetIndent,
 } from "../file/context.js";
-import { fileFormatInlineComment } from "../file/format.js";
+import { fileFormatInlineComment } from "../file/docs.js";
 import { fileWrite, fileWriteInline } from "../file/write.js";
 import { modelKeyGetPrimary } from "../processors/model-keys.js";
 import {

diff --git a/packages/code-gen/src/experimental/database/postgres.js b/packages/code-gen/src/experimental/database/postgres.js
@@ -4,7 +4,7 @@ import {
   fileContextCreateGeneric,
   fileContextSetIndent,
 } from "../file/context.js";
-import { fileFormatInlineComment } from "../file/format.js";
+import { fileFormatInlineComment } from "../file/docs.js";
 import { fileWrite, fileWriteInline } from "../file/write.js";
 import {
   modelKeyGetPrimary,

diff --git a/packages/code-gen/src/experimental/file/context.js b/packages/code-gen/src/experimental/file/context.js
@@ -1,5 +1,5 @@
 import { AppError } from "@compas/stdlib";
-import { fileFormatInlineComment } from "./format.js";
+import { fileFormatInlineComment } from "./docs.js";
 import {
   fileImportsAddPlaceholder,
   fileImportsStringifyImports,

diff --git a/packages/code-gen/src/experimental/file/docs.d.ts b/packages/code-gen/src/experimental/file/docs.d.ts
@@ -0,0 +1,24 @@
+/**
+ * Format the provided contents as an inline comment for the specific file.
+ *
+ * @param {import("./context").GenerateFile} file
+ * @param {string} contents
+ * @returns {string}
+ */
+export function fileFormatInlineComment(
+  file: import("./context").GenerateFile,
+  contents: string,
+): string;
+/**
+ * Format the provided contents as a doc block comment. Compatible with things like JSDoc
+ * blocks.
+ *
+ * @param {import("./context").GenerateFile} file
+ * @param {string} contents
+ * @returns {void}
+ */
+export function fileWriteDocBlock(
+  file: import("./context").GenerateFile,
+  contents: string,
+): void;
+//# sourceMappingURL=docs.d.ts.map
diff --git a/packages/code-gen/src/experimental/file/docs.js b/packages/code-gen/src/experimental/file/docs.js
@@ -0,0 +1,36 @@
+import {
+  fileContextAddLinePrefix,
+  fileContextRemoveLinePrefix,
+} from "./context.js";
+import { fileWrite } from "./write.js";
+
+/**
+ * Format the provided contents as an inline comment for the specific file.
+ *
+ * @param {import("./context").GenerateFile} file
+ * @param {string} contents
+ * @returns {string}
+ */
+export function fileFormatInlineComment(file, contents) {
+  return `${file.inlineCommentPrefix}${contents.replace(
+    /\n/g,
+    `\n${file.inlineCommentPrefix}`,
+  )}`;
+}
+
+/**
+ * Format the provided contents as a doc block comment. Compatible with things like JSDoc
+ * blocks.
+ *
+ * @param {import("./context").GenerateFile} file
+ * @param {string} contents
+ * @returns {void}
+ */
+export function fileWriteDocBlock(file, contents) {
+  fileWrite(file, `/**`);
+  fileContextAddLinePrefix(file, " * ");
+  fileWrite(file, contents);
+
+  fileContextRemoveLinePrefix(file, 3);
+  fileWrite(file, " */");
+}
diff --git a/packages/code-gen/src/experimental/file/format.d.ts b/packages/code-gen/src/experimental/file/format.d.ts
diff --git a/packages/code-gen/src/experimental/file/format.js b/packages/code-gen/src/experimental/file/format.js