feat: jsdocs for generated types, by using admin.description (#9917)

This makes use of admin.description to generate JSDocs for field,
collection and global generated types.


![image](https://github.com/user-attachments/assets/980d825f-49a2-426d-933a-2ff3d205ea24)


![image](https://github.com/user-attachments/assets/d0b1f288-1ea1-4d80-8c05-003d59a4e41a)

For the future, we should add a dedicated property to override these
JSDocs.

You can view the effect of this PR on our test suite generated types
here:
05f552b

Author: AlessioGr

packages/payload/src/admin/RichText.ts

@@ -215,16 +215,11 @@ type RichTextAdapterBase<
   }) => void
   hooks?: RichTextHooks
   i18n?: Partial<GenericLanguages>
-  outputSchema?: ({
-    collectionIDFieldTypes,
-    config,
-    field,
-    interfaceNameDefinitions,
-    isRequired,
-  }: {
+  outputSchema?: (args: {
     collectionIDFieldTypes: { [key: string]: 'number' | 'string' }
     config?: SanitizedConfig
     field: RichTextField<Value, AdapterProps, ExtraFieldProperties>
+    i18n?: I18n
     /**
      * Allows you to define new top-level interfaces that can be re-used in the output schema.
      */

packages/payload/src/bin/generateTypes.ts

@@ -1,3 +1,4 @@
+import { initI18n } from '@payloadcms/translations'
 import fs from 'fs'
 import { compile } from 'json-schema-to-typescript'
 
@@ -19,8 +20,9 @@ export async function generateTypes(
   if (shouldLog) {
     logger.info('Compiling TS types for Collections and Globals...')
   }
+  const i18n = await initI18n({ config: config.i18n, context: 'api', language: 'en' })
 
-  const jsonSchema = configToJSONSchema(config, config.db.defaultIDType)
+  const jsonSchema = configToJSONSchema(config, config.db.defaultIDType, i18n)
 
   const declare = `declare module 'payload' {\n  export interface GeneratedTypes extends Config {}\n}`
   const declareWithTSIgnoreError = `declare module 'payload' {\n  // @ts-ignore \n  export interface GeneratedTypes extends Config {}\n}`

packages/payload/src/collections/config/types.ts

@@ -329,7 +329,7 @@ export type CollectionAdminOptions = {
    */
   defaultColumns?: string[]
   /**
-   * Custom description for collection
+   * Custom description for collection. This will also be used as JSDoc for the generated types
    */
   description?: EntityDescription
   enableRichTextLink?: boolean

packages/payload/src/fields/config/types.ts

@@ -280,6 +280,10 @@ type Admin = {
   condition?: Condition
   /** Extension point to add your custom data. Available in server and client. */
   custom?: Record<string, any>
+  /**
+   * The field description will be displayed next to the field in the admin UI. Additionally,
+   * we use the field description to generate JSDoc comments for the generated TypeScript types.
+   */
   description?: Description
   disableBulkEdit?: boolean
   disabled?: boolean

packages/payload/src/queues/config/generateJobsJSONSchemas.ts

@@ -1,11 +1,11 @@
+import type { I18n } from '@payloadcms/translations'
 import type { JSONSchema4 } from 'json-schema'
 
 import type { SanitizedConfig } from '../../config/types.js'
 import type { JobsConfig } from './types/index.js'
 
 import { fieldsToJSONSchema } from '../../utilities/configToJSONSchema.js'
 import { flattenAllFields } from '../../utilities/flattenAllFields.js'
-
 export function generateJobsJSONSchemas(
   config: SanitizedConfig,
   jobsConfig: JobsConfig,
@@ -16,6 +16,7 @@ export function generateJobsJSONSchemas(
    * if they have custom ID fields.
    */
   collectionIDFieldTypes: { [key: string]: 'number' | 'string' },
+  i18n?: I18n,
 ): {
   definitions?: Map<string, JSONSchema4>
   properties?: { tasks: JSONSchema4 }
@@ -43,6 +44,7 @@ export function generateJobsJSONSchemas(
           flattenAllFields({ fields: task.inputSchema }),
           interfaceNameDefinitions,
           config,
+          i18n,
         )
 
         const fullInputJsonSchema: JSONSchema4 = {
@@ -61,6 +63,7 @@ export function generateJobsJSONSchemas(
           flattenAllFields({ fields: task.outputSchema }),
           interfaceNameDefinitions,
           config,
+          i18n,
         )
 
         const fullOutputJsonSchema: JSONSchema4 = {
@@ -127,6 +130,7 @@ export function generateJobsJSONSchemas(
           flattenAllFields({ fields: workflow.inputSchema }),
           interfaceNameDefinitions,
           config,
+          i18n,
         )
 
         const fullInputJsonSchema: JSONSchema4 = {