fix: fix typedoc annotations for hooks (#361)

* fix: fix typedoc annotations for hooks:

- adds @function tag for hooks exported as constants
- adds @interface for ProjectWithoutMembers type to expand dynamic
  properties
- corrects mention of which datasets returned by useDatasets
- corrects mention of which projects returned by useProjects

* fix: add missing tsdoc tag definitions

* fix: add missing custom tsdoc tags

* fix: useDocuments->useInfiniteList in usePreview example

Author: colepeters

packages/@repo/package.config/src/package.config.ts

@@ -28,6 +28,16 @@ export const basePackageConfig = defineConfig({
         allowMultiple: true,
         syntaxKind: 'block',
       },
+      {
+        name: 'function',
+        allowMultiple: false,
+        syntaxKind: 'modifier',
+      },
+      {
+        name: 'interface',
+        syntaxKind: 'modifier',
+        allowMultiple: false,
+      },
     ],
   },
 })

packages/core/src/tsdoc.json

@@ -15,6 +15,16 @@
       "tagName": "@thoughtLevel",
       "syntaxKind": "block",
       "allowMultiple": true
+    },
+    {
+      "tagName": "@interface",
+      "syntaxKind": "modifier",
+      "allowMultiple": false
+    },
+    {
+      "tagName": "@function",
+      "syntaxKind": "modifier",
+      "allowMultiple": false
     }
   ],
   "supportForTags": {
@@ -34,6 +44,8 @@
     "@see": true,
     "@thoughtLevel": true,
     "@throws": true,
-    "@todo": true
+    "@todo": true,
+    "@interface": true,
+    "@function": true
   }
 }

packages/core/tsdoc.json

@@ -15,6 +15,16 @@
       "tagName": "@category",
       "syntaxKind": "block",
       "allowMultiple": true
+    },
+    {
+      "tagName": "@function",
+      "syntaxKind": "modifier",
+      "allowMultiple": false
+    },
+    {
+      "tagName": "@interface",
+      "syntaxKind": "modifier",
+      "allowMultiple": false
     }
   ],
   "supportForTags": {
@@ -34,6 +44,8 @@
     "@throws": true,
     "@defaultValue": true,
     "@todo": true,
-    "@category": true
+    "@category": true,
+    "@function": true,
+    "@interface": true
   }
 }

packages/react-internal/tsdoc.json

@@ -10,6 +10,16 @@
       "tagName": "@todo",
       "syntaxKind": "block",
       "allowMultiple": true
+    },
+    {
+      "tagName": "@function",
+      "syntaxKind": "modifier",
+      "allowMultiple": false
+    },
+    {
+      "tagName": "@interface",
+      "syntaxKind": "modifier",
+      "allowMultiple": false
     }
   ],
   "supportForTags": {
@@ -28,6 +38,8 @@
     "@remarks": true,
     "@throws": true,
     "@defaultValue": true,
-    "@todo": true
+    "@todo": true,
+    "@function": true,
+    "@interface": true
   }
 }

packages/react/src/hooks/auth/useCurrentUser.tsx

@@ -28,6 +28,7 @@ type UseCurrentUser = {
 
 /**
  * @public
+ * @function
  * @TODO This should not return null — users of a custom app will always be authenticated via Core
  */
 export const useCurrentUser: UseCurrentUser = createStateSourceHook(getCurrentUserState)

packages/react/src/hooks/client/useClient.ts

@@ -27,6 +27,7 @@ import {createStateSourceHook} from '../helpers/createStateSourceHook'
  * ```
  *
  * @public
+ * @function
  */
 export const useClient = createStateSourceHook({
   getState: getClientState,

packages/react/src/hooks/datasets/useDatasets.ts

@@ -6,10 +6,10 @@ import {createStateSourceHook} from '../helpers/createStateSourceHook'
 type UseDatasets = {
   /**
    *
-   * Returns metadata for each dataset in your organization.
+   * Returns metadata for each dataset the current user has access to.
    *
    * @category Datasets
-   * @returns The metadata for your organization's datasets
+   * @returns The metadata for your the datasets
    *
    * @example
    * ```tsx
@@ -28,7 +28,10 @@ type UseDatasets = {
   (): DatasetsResponse
 }
 
-/** @public */
+/**
+ * @public
+ * @function
+ */
 export const useDatasets: UseDatasets = createStateSourceHook({
   // remove `undefined` since we're suspending when that is the case
   getState: getDatasetsState as (instance: SanityInstance) => StateSource<DatasetsResponse>,

packages/react/src/hooks/document/useDocumentSyncStatus.ts

@@ -25,6 +25,9 @@ type UseDocumentSyncStatus = {
   (doc: DocumentHandle): boolean | undefined
 }
 
-/** @beta */
+/**
+ * @beta
+ * @function
+ */
 export const useDocumentSyncStatus: UseDocumentSyncStatus =
   createStateSourceHook(getDocumentSyncStatus)

packages/react/src/hooks/preview/usePreview.tsx

@@ -36,7 +36,7 @@ export interface UsePreviewResults {
  * @param options - The document handle for the document you want to resolve preview values for, and an optional ref
  * @returns The preview values for the given document and a boolean to indicate whether the resolution is pending
  *
- * @example Combining with useDocuments to render a collection of document previews
+ * @example Combining with useInfiniteList to render a collection of document previews
  * ```
  * // PreviewComponent.jsx
  * export default function PreviewComponent({ document }) {
@@ -51,12 +51,12 @@ export interface UsePreviewResults {
  * }
  *
  * // DocumentList.jsx
- * const { data, isPending } = useDocuments({ filter: '_type == "movie"' })
+ * const { data } = useInfiniteList({ filter: '_type == "movie"' })
  * return (
  *   <div>
  *     <h1>Movies</h1>
  *     <ul>
- *       {isPending ? 'Loading…' : data.map(movie => (
+ *       {data.map(movie => (
  *         <li key={movie._id}>
  *           <Suspense fallback='Loading…'>
  *             <PreviewComponent document={movie} />

packages/react/src/hooks/projects/useProject.ts

@@ -32,7 +32,10 @@ type UseProject = {
   (projectId: string): SanityProject
 }
 
-/** @public */
+/**
+ * @public
+ * @function
+ */
 export const useProject: UseProject = createStateSourceHook({
   // remove `undefined` since we're suspending when that is the case
   getState: getProjectState as (