fix(codegen): update help text and generated comments copy (#6059)

* fix(codegen): update help text and generated comments copy

co-authored-by: Knut Melvær <knut@sanity.io>

* fix: new lines

Co-authored-by: Knut Melvær <knut@sanity.io>

---------

Co-authored-by: Knut Melvær <knut@sanity.io>

Author: sgulseth

packages/sanity/src/_internal/cli/actions/typegen/generateAction.ts

@@ -16,6 +16,20 @@ export interface TypegenGenerateTypesCommandFlags {
   configPath?: string
 }
 
+const generatedFileWarning = `/**
+ * ---------------------------------------------------------------------------------
+ * This file has been generated by Sanity TypeGen.
+ * Command: \`sanity typegen generate\`
+ *
+ * Any modifications made directly to this file will be overwritten the next time
+ * the TypeScript definitions are generated. Please make changes to the Sanity
+ * schema definitions and/or GROQ queries if you need to update these types.
+ *
+ * For more information on how to use Sanity TypeGen, visit the official documentation:
+ * https://www.sanity.io/docs/sanity-typegen
+ * ---------------------------------------------------------------------------------
+ */\n\n`
+
 export default async function typegenGenerateAction(
   args: CliCommandArguments<TypegenGenerateTypesCommandFlags>,
   context: CliCommandContext,
@@ -30,7 +44,7 @@ export default async function typegenGenerateAction(
 
   const rootPkgPath = readPkgUp.sync({cwd: __dirname})?.path
   if (!rootPkgPath) {
-    throw new Error('Could not find root directory for `sanity` package')
+    throw new Error('Could not find the root directory for the `sanity` package')
   }
 
   const workerPath = join(
@@ -60,7 +74,7 @@ export default async function typegenGenerateAction(
     constants.O_TRUNC | constants.O_CREAT | constants.O_WRONLY,
   )
 
-  typeFile.write('// This file is generated by `sanity typegen generate`\n')
+  typeFile.write(generatedFileWarning)
 
   const stats = {
     files: 0,
@@ -91,7 +105,7 @@ export default async function typegenGenerateAction(
         return
       }
 
-      let fileTypeString = `// ${msg.filename}\n`
+      let fileTypeString = `// Source: ${msg.filename}\n`
 
       if (msg.type === 'schema') {
         stats.schemas += msg.length
@@ -102,8 +116,8 @@ export default async function typegenGenerateAction(
 
       stats.files++
       for (const {queryName, query, type, unknownTypes} of msg.types) {
-        fileTypeString += `// ${queryName}\n`
-        fileTypeString += `// ${query.replace(/(\r\n|\n|\r)/gm, '')}\n`
+        fileTypeString += `// Variable: ${queryName}\n`
+        fileTypeString += `// Query: ${query.replace(/(\r\n|\n|\r)/gm, '')}\n`
         fileTypeString += `${type}\n`
         stats.queries++
         stats.unknownTypes += unknownTypes
@@ -131,6 +145,6 @@ export default async function typegenGenerateAction(
   }
 
   spinner.succeed(
-    `Generated TypeScript types for ${stats.schemas} schema types and ${stats.queries} queries in ${stats.files} files into: ${codegenConfig.generates}`,
+    `Generated TypeScript types for ${stats.schemas} schema types and ${stats.queries} GROQ queries in ${stats.files} files into: ${codegenConfig.generates}`,
   )
 }

packages/sanity/src/_internal/cli/commands/typegen/generateTypesCommand.ts

@@ -1,27 +1,39 @@
 import {type CliCommandDefinition} from '@sanity/cli'
 
-const description = 'Generates types'
+const description = 'Generates TypeScript types from schema types and GROQ queries'
 
 const helpText = `
-**Note**: This command is experimental and subject to change.
+Sanity TypeGen (Beta)
+This command is currently in beta and may undergo significant changes. Feedback is welcome!
 
-Options
+Usage
+  sanity typegen generate [options]
+
+Options:
   --help, -h
-    Show this help text.
+    Displays this help message, providing information on command usage and options.
+
+Examples:
+  Generate TypeScript type definitions from a Sanity Studio schema extracted using the \`sanity schema extract\` command.
+    $ sanity typegen generate
+
+Configuration:
+This command can utilize configuration settings defined in a \`sanity-typegen.json\` file. These settings include:
+
+- "path": Specifies a glob pattern to locate your TypeScript or JavaScript files.
+  Default: "./src/**/*.{ts,tsx,js,jsx}"
+
+- "schema": Defines the path to your Sanity schema file. This file should be generated using the \`sanity schema extract\` command.
+  Default: "schema.json"
 
-Examples
-  # Generate types from a schema, generate schema with "sanity schema extract" first.
-  sanity typegen generate
+- "generates": Indicates the path where the generated TypeScript type definitions will be saved.
+  Default: "./sanity.types.ts"
 
-Configuration
-The command uses the following configuration properties from sanity-typegen.json:
-{
-  "path": "'./src/**/*.{ts,tsx,js,jsx}'" // glob pattern to your typescript files
-  "schema": "schema.json", // path to your schema file, generated with 'sanity schema extract' command
-  "generates": "./sanity.types.ts" // path to the file where the types will be generated
-}
+The default configuration values listed above are used if not overridden in your \`sanity-typegen.json\` configuration file. To customize the behavior of the type generation, adjust these properties in the configuration file according to your project's needs.
 
-The listed properties are the default values, and can be overridden in the configuration file.
+Note:
+- The \`sanity schema extract\` command is a prerequisite for extracting your Sanity Studio schema into a \`schema.json\` file, which is then used by the \`sanity typegen generate\` command to generate type definitions.
+- While this tool is in beta, we encourage you to experiment with these configurations and provide feedback to help improve its functionality and usability.
 `
 
 const generateTypegenCommand: CliCommandDefinition = {