fix(docs): complete apidocs for migrations (#5679)

* fix(migrate): add tsdoc config

* fix(docs): complete apidocs for migrations

Co-Authored-By: Knut Melvær <[email protected]>

* fixup! fix(docs): complete apidocs for migrations

Co-Authored-By: Knut Melvær <[email protected]>
Co-authored-by: Binoy Patel <[email protected]>

* fixup! fix(docs): complete apidocs for migrations

---------

Co-authored-by: Knut Melvær <[email protected]>
Co-authored-by: Binoy Patel <[email protected]>

packages/@sanity/migrate/src/defineMigration.ts

@@ -1,5 +1,31 @@
 import {type Migration} from './types'
 
+/**
+ * @public
+ *
+ * Helper function for defining a Sanity content migration. This function does not do anything on its own;
+ * it exists to check that your schema definition is correct, and help autocompletion in your IDE.
+ *
+ * {@link https://www.sanity.io/docs/schema-and-content-migrations#af2be129ccd6}
+
+ * @example Basic usage
+ *
+ * ```ts
+ * export default defineMigration({
+ *  title: 'Make sure all strings with “acme” is uppercased to “ACME”',
+ *  migrate: {
+ *    string(node, path, context) {
+ *      if (node === "acme") {
+ *        return set(node.toUpperCase())
+ *      }
+ *    },
+ *  },
+ * })
+ * ```
+ * @param migration - The migration definition
+ *
+ * See {@link Migration}
+ */
 export function defineMigration<T extends Migration>(migration: T): T {
   return migration
 }

packages/@sanity/migrate/src/mutations/creators.ts

@@ -19,7 +19,7 @@ import {type NormalizeReadOnlyArray, type Optional, type Tuplify} from './typeUt
 /**
  * Creates a new document.
  * @param document - The document to be created.
- * @returns The mutation operation to create the document.
+ * @returns The mutation to create the document.
  * @beta
  */
 export function create<Doc extends Optional<SanityDocument, '_id'>>(
@@ -30,10 +30,10 @@ export function create<Doc extends Optional<SanityDocument, '_id'>>(
 
 /**
  * Applies a patch to a document.
- * @param id - The id of the document to be patched.
+ * @param id - The ID of the document to be patched.
  * @param patches - The patches to be applied.
  * @param options - Optional patch options.
- * @returns The mutation operation to patch the document.
+ * @returns The mutation to patch the document.
  * @beta
  */
 export function patch<P extends NodePatchList | NodePatch>(
@@ -50,7 +50,7 @@ export function patch<P extends NodePatchList | NodePatch>(
 }
 
 /**
- * Creates a node patch at a specific path.
+ * Creates a {@link NodePatch} at a specific path.
  * @param path - The path where the operation should be applied.
  * @param operation - The operation to be applied.
  * @returns The node patch.
@@ -98,6 +98,6 @@ export function delete_(id: string): DeleteMutation {
 }
 
 /**
- * Alias for delete_
+ * Alias for delete
  */
 export const del = delete_

packages/@sanity/migrate/src/mutations/operations/creators.ts

@@ -22,6 +22,12 @@ import {
  * @returns A `set` operation.
  * {@link https://www.sanity.io/docs/http-patches#6TPENSW3}
  * @beta
+ *
+ * @example
+ * ```ts
+ * const setFoo = set('foo')
+ * const setEmptyArray = set([])
+ * ```
  */
 export const set = <const T>(value: T): SetOp<T> => ({type: 'set', value})
 
@@ -31,6 +37,11 @@ export const set = <const T>(value: T): SetOp<T> => ({type: 'set', value})
  * @returns A `setIfMissing` operation.
  * {@link https://www.sanity.io/docs/http-patches#A80781bT}
  * @beta
+ * @example
+ * ```ts
+ * const setFooIfMissing = setIfMissing('foo')
+ * const setEmptyArrayIfMissing = setIfMissing([])
+ * ```
  */
 export const setIfMissing = <const T>(value: T): SetIfMissingOp<T> => ({
   type: 'setIfMissing',
@@ -42,15 +53,26 @@ export const setIfMissing = <const T>(value: T): SetIfMissingOp<T> => ({
  * @returns An `unset` operation.
  * {@link https://www.sanity.io/docs/http-patches#xRtBjp8o}
  * @beta
+ *
+ * @example
+ * ```ts
+ * const unsetAnyValue = unset()
+ * ```
  */
 export const unset = (): UnsetOp => ({type: 'unset'})
 
 /**
  * Creates an `inc` (increment) operation with the provided amount.
  * @param amount - The amount to increment by.
- * @returns An `inc` operation.
+ * @returns An incrementation operation for numeric values
  * {@link https://www.sanity.io/docs/http-patches#vIT8WWQo}
  * @beta
+ *
+ * @example
+ * ```ts
+ * const incBy1 = inc()
+ * const incBy5 = inc(5)
+ * ```
  */
 export const inc = <const N extends number = 1>(amount: N = 1 as N): IncOp<N> => ({
   type: 'inc',
@@ -63,6 +85,12 @@ export const inc = <const N extends number = 1>(amount: N = 1 as N): IncOp<N> =>
  * @returns A `dec` operation.
  * {@link https://www.sanity.io/docs/http-patches#vIT8WWQo}
  * @beta
+ *
+ * @example
+ * ```ts
+ * const decBy1 = dec()
+ * const decBy10 = dec(10)
+ * ```
  */
 export const dec = <const N extends number = 1>(amount: N = 1 as N): DecOp<N> => ({
   type: 'dec',
@@ -74,7 +102,7 @@ export const dec = <const N extends number = 1>(amount: N = 1 as N): DecOp<N> =>
  * @param value - The value for the diff match patch operation.
  * @returns A `diffMatchPatch` operation.
  * {@link https://www.sanity.io/docs/http-patches#aTbJhlAJ}
- * @beta
+ * @public
  */
 export const diffMatchPatch = (value: string): DiffMatchPatchOp => ({
   type: 'diffMatchPatch',
@@ -86,9 +114,16 @@ export const diffMatchPatch = (value: string): DiffMatchPatchOp => ({
  * @param items - The items to insert.
  * @param position - The position to insert at.
  * @param indexOrReferenceItem - The index or reference item to insert before or after.
- * @returns An `insert` operation.
+ * @returns An `insert` operation for adding values to arrays
  * {@link https://www.sanity.io/docs/http-patches#febxf6Fk}
  * @beta
+ *
+ * @example
+ * ```ts
+ * const prependFoo = insert(['foo'], 'before')
+ * const appendFooAndBar = insert(['foo', 'bar'], 'after')
+ * const insertObjAfterXYZ = insert({name: 'foo'}, 'after', {_key: 'xyz'}])
+ * ```
  */
 export function insert<
   const Items extends AnyArray<unknown>,
@@ -110,9 +145,16 @@ export function insert<
 /**
  * Creates an `insert` operation that appends the provided items.
  * @param items - The items to append.
- * @returns An `insert` operation at the end of the array.
+ * @returns An `insert` operation for adding a value to the end of an array.
  * {@link https://www.sanity.io/docs/http-patches#Cw4vhD88}
  * @beta
+ *
+ * @example
+ * ```ts
+ * const appendFoo = append('foo')
+ * const appendObject = append({name: 'foo'})
+ * const appendObjects = append([{name: 'foo'}, [{name: 'bar'}]])
+ * ```
  */
 export function append<const Items extends AnyArray<unknown>>(items: Items | ArrayElement<Items>) {
   return insert(items, 'after', -1)
@@ -121,9 +163,16 @@ export function append<const Items extends AnyArray<unknown>>(items: Items | Arr
 /**
  * Creates an `insert` operation that prepends the provided items.
  * @param items - The items to prepend.
- * @returns An `insert` operation at the beginning of the array.
+ * @returns An `insert` operation for adding a value to the start of an array.
  * {@link https://www.sanity.io/docs/http-patches#refAUsf0}
  * @beta
+ *
+ * @example
+ * ```ts
+ * const prependFoo = prepend('foo')
+ * const prependObject = prepend({name: 'foo'})
+ * const prependObjects = prepend([{name: 'foo'}, [{name: 'bar'}]])
+ * ```
  */
 export function prepend<const Items extends AnyArray<unknown>>(items: Items | ArrayElement<Items>) {
   return insert(items, 'before', 0)
@@ -135,6 +184,13 @@ export function prepend<const Items extends AnyArray<unknown>>(items: Items | Ar
  * @param indexOrReferenceItem - The index or reference item to insert before.
  * @returns An `insert` operation before the provided index or reference item.
  * {@link https://www.sanity.io/docs/http-patches#0SQmPlb6}
+ * @public
+ *
+ * @example
+ * ```ts
+ * const insertFooBeforeIndex3 = insertBefore('foo', 3)
+ * const insertObjectBeforeKey = insertBefore({name: 'foo'}, {_key: 'xyz'}]
+ * ```
  */
 export function insertBefore<
   const Items extends AnyArray<unknown>,
@@ -150,6 +206,12 @@ export function insertBefore<
  * @returns An `insert` operation after the provided index or reference item.
  * {@link https://www.sanity.io/docs/http-patches#0SQmPlb6}
  * @beta
+ *
+ * @example
+ * ```ts
+ * const insertFooAfterIndex3 = insertAfter('foo', 3)
+ * const insertObjectAfterKey = insertAfter({name: 'foo'}, {_key: 'xyz'}]
+ * ```
  */
 export const insertAfter = <
   const Items extends AnyArray<unknown>,
@@ -169,6 +231,13 @@ export const insertAfter = <
  * @remarks - This will be converted to an `unset` patch when submitted to the API
  * {@link https://www.sanity.io/docs/http-patches#xRtBjp8o}
  * @beta
+ *
+ * @example
+ * ```ts
+ * const clearArray = truncate(0)
+ * const removeItems = truncate(3, 5) // Removes items at index 3, 4, and 5
+ * const truncate200 = truncate(200) // Removes all items after index 200
+ * ```
  */
 export function truncate(startIndex: number, endIndex?: number): TruncateOp {
   return {
@@ -186,6 +255,13 @@ export function truncate(startIndex: number, endIndex?: number): TruncateOp {
  * @remarks This will be converted to an `insert`/`replace` patch when submitted to the API
  * {@link https://www.sanity.io/docs/http-patches#GnVSwcPa}
  * @beta
+ *
+ * @example
+ * ```ts
+ * const replaceItem3WithFoo = replace('foo', 3)
+ * const replaceItem3WithFooAndBar = replace(['foo', 'bar'], 3)
+ * const replaceObject = replace({name: 'bar'}, {_key: 'xyz'})
+ * ```
  */
 export function replace<Items extends any[], ReferenceItem extends IndexedSegment | KeyedSegment>(
   items: Items | ArrayElement<Items>,