Merge remote-tracking branch 'origin/main'

example.ts

@@ -12,6 +12,7 @@ import { run } from "./src/generate"
       watch: false,
       asserts: true,
       defaultArrayCheckOption: "all",
+      comment: false,
     },
   })
 })()

src/cli.ts

@@ -21,6 +21,7 @@ program
     "how to check child element type. 'all' or 'first'",
     "all"
   )
+  .option("-c, --comment", "generate JSDoc comments or not", false)
   .parse(process.argv)
 
 const option = program.opts<{
@@ -31,6 +32,7 @@ const option = program.opts<{
   asserts: boolean
   watch: boolean
   defaultArrayCheckOption: ArrayCheckOption
+  comment: boolean
 }>()
 
 const cwd = process.cwd()
@@ -44,5 +46,6 @@ run({
     asserts: option.asserts,
     watch: option.watch,
     defaultArrayCheckOption: option.defaultArrayCheckOption,
+    comment: option.comment,
   },
 })

src/generate/generate-type-predicates.ts

@@ -122,7 +122,8 @@ export function generateTypePredicates(
     }[]
   }[],
   asserts = false,
-  defaultArrayCheckOption: ArrayCheckOption = "all"
+  defaultArrayCheckOption: ArrayCheckOption = "all",
+  comment = false
 ): string {
   const usedPrimitives: to.PrimitiveTO["kind"][] = []
   const usedSpecials: to.SpecialTO["kind"][] = []
@@ -236,6 +237,38 @@ export function generateTypePredicates(
     }`
   }
 
+  const generateJSDocComment = ({
+    type,
+    typeName,
+    isAssertion,
+  }: {
+    type: to.TypeObject
+    typeName: string
+    isAssertion: boolean
+  }): string => {
+    return isAssertion
+      ? `\
+/**
+ * Assert if a variable is of type {@link ${typeName}} and throws a TypeError if the assertion fails.
+ * This function is automatically generated using [type-predicates-generator](https://www.npmjs.com/package/type-predicates-generator).
+ * @param value Argument to inspect.
+ * @throw TypeError if the given argument is not compatible with the type {@link ${typeName}}.
+ */
+`
+      : `\
+/**
+ * Check if a variable is of type {@link ${typeName}} and narrow it down to that type if the check passes.
+ * This function is automatically generated using [type-predicates-generator](https://www.npmjs.com/package/type-predicates-generator).
+ * @param arg_0 Argument to inspect.${
+    type.__type === "ArrayTO"
+      ? "\n * @param checkOpt Whether to check all elements of the array or only the first one."
+      : ""
+  }
+ * @return \`true\` if the argument is of type {@link ${typeName}}, \`false\` otherwise.
+ */
+`
+  }
+
   const generatedTypeNames: string[] = []
   const skipImports: {
     typeName: string
@@ -281,14 +314,22 @@ export function generateTypePredicates(
 
       generatedTypeNames.push(typeName)
 
-      return `export const is${typeName} = ${generateCheckFn({
+      return `${
+        comment
+          ? generateJSDocComment({ type, typeName, isAssertion: false })
+          : ""
+      }export const is${typeName} = ${generateCheckFn({
         type,
         typeName,
         parentArgCount: -1,
       })};
 ${
   asserts
-    ? `export function assertIs${typeName}(value: unknown): asserts value is ${typeName} {
+    ? `${
+        comment
+          ? generateJSDocComment({ type, typeName, isAssertion: true })
+          : ""
+      }export function assertIs${typeName}(value: unknown): asserts value is ${typeName} {
   if (!is${typeName}(value)) throw new TypeError(\`value must be ${typeName} but received \${value}\`)
 };`
     : ""

src/generate/index.ts

@@ -15,6 +15,7 @@ type GenerateOption = {
   asserts: boolean
   watch: boolean
   defaultArrayCheckOption: ArrayCheckOption
+  comment: boolean
 }
 
 export async function run({
@@ -84,7 +85,7 @@ const generateAndWriteCodes = (
   program: ts.Program,
   files: string[],
   output: string,
-  { asserts, defaultArrayCheckOption }: GenerateOption
+  { asserts, defaultArrayCheckOption, comment }: GenerateOption
 ) => {
   const handler = new CompilerApiHandler(program)
 
@@ -116,7 +117,8 @@ const generateAndWriteCodes = (
   const generatedCode = generateTypePredicates(
     types,
     asserts,
-    defaultArrayCheckOption
+    defaultArrayCheckOption,
+    comment
   )
   writeFileSync(output, generatedCode)
 }