docs: add tsdocs for hooks

prismicio · Aug 16, 2021 · 0b1a610 · 0b1a610
1 parent 8abfc9a
commit 0b1a610
Showing 1 changed file with 194 additions and 0 deletions.
diff --git a/src/hooks.ts b/src/hooks.ts
@@ -10,25 +10,78 @@ import {
 
 const proto = prismic.Client.prototype;
 
+/**
+ * A hook that queries content from the Prismic repository.
+ *
+ * @param params - Parameters to filter, sort, and paginate results
+ *
+ * @returns The composable payload {@link ClientHookReturnType}
+ *
+ * @typeParam TDocument - Type of Prismic documents returned
+ *
+ * @remarks An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
+ * @see Underlying `@prismicio/client` method {@link proto.get}
+ */
 export const usePrismicDocuments = <TDocument extends prismicT.PrismicDocument>(
 	...args: [params?: ClientMethodParameters<"get">[0] & HookOnlyParameters]
 ): ClientHookReturnType<prismic.Query<TDocument>> =>
 	useStatefulPrismicClientMethod(proto.get, args);
 
+/**
+ * A hook that queries content from the Prismic repository and returns only the first result, if any.
+ *
+ * @param params - Parameters to filter, sort, and paginate results
+ *
+ * @returns The composable payload {@link ClientHookReturnType}
+ *
+ * @typeParam TDocument - Type of the Prismic document returned
+ *
+ * @remarks An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
+ * @see Underlying `@prismicio/client` method {@link proto.getFirst}
+ */
 export const useFirstPrismicDocument = <
 	TDocument extends prismicT.PrismicDocument,
 >(
 	...args: [params?: ClientMethodParameters<"getFirst">[0] & HookOnlyParameters]
 ): ClientHookReturnType<TDocument> =>
 	useStatefulPrismicClientMethod(proto.getFirst, args);
 
+/**
+ * A hook that queries content from the Prismic repository and returns all matching content. If no predicates are provided, all documents will be fetched.
+ *
+ * @param params - Parameters to filter and sort results
+ *
+ * @returns The composable payload {@link ClientHookReturnType}
+ *
+ * @typeParam TDocument - Type of Prismic documents returned
+ *
+ * @remarks An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
+ * @see Underlying `@prismicio/client` method {@link proto.getAll}
+ */
 export const useAllPrismicDocuments = <
 	TDocument extends prismicT.PrismicDocument,
 >(
 	...args: [params?: ClientMethodParameters<"getAll">[0] & HookOnlyParameters]
 ): ClientHookReturnType<TDocument[]> =>
 	useStatefulPrismicClientMethod(proto.getAll, args);
 
+/**
+ * A hook that queries a document from the Prismic repository with a specific ID.
+ *
+ * @param id - ID of the document
+ * @param params - Parameters to filter, sort, and paginate results
+ *
+ * @returns The composable payload {@link ClientHookReturnType}
+ *
+ * @typeParam TDocument - Type of the Prismic document returned
+ *
+ * @remarks An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
+ * @see Underlying `@prismicio/client` method {@link proto.getByID}
+ */
 export const usePrismicDocumentByID = <
 	TDocument extends prismicT.PrismicDocument,
 >(
@@ -39,6 +92,20 @@ export const usePrismicDocumentByID = <
 ): ClientHookReturnType<TDocument> =>
 	useStatefulPrismicClientMethod(proto.getByID, args);
 
+/**
+ * A hook that queries documents from the Prismic repository with specific IDs.
+ *
+ * @param ids - A list of document IDs
+ * @param params - Parameters to filter, sort, and paginate results
+ *
+ * @returns The composable payload {@link ClientHookReturnType}
+ *
+ * @typeParam TDocument - Type of Prismic documents returned
+ *
+ * @remarks An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
+ * @see Underlying `@prismicio/client` method {@link proto.getByIDs}
+ */
 export const usePrismicDocumentsByIDs = <
 	TDocument extends prismicT.PrismicDocument,
 >(
@@ -49,6 +116,20 @@ export const usePrismicDocumentsByIDs = <
 ): ClientHookReturnType<prismic.Query<TDocument>> =>
 	useStatefulPrismicClientMethod(proto.getByIDs, args);
 
+/**
+ * A hook that queries all documents from the Prismic repository with specific IDs.
+ *
+ * @param ids - A list of document IDs
+ * @param params - Parameters to filter and sort results
+ *
+ * @returns The composable payload {@link ClientHookReturnType}
+ *
+ * @typeParam TDocument - Type of Prismic documents returned
+ *
+ * @remarks An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
+ * @see Underlying `@prismicio/client` method {@link proto.getAllByIDs}
+ */
 export const useAllPrismicDocumentsByIDs = <
 	TDocument extends prismicT.PrismicDocument,
 >(
@@ -59,6 +140,21 @@ export const useAllPrismicDocumentsByIDs = <
 ): ClientHookReturnType<TDocument[]> =>
 	useStatefulPrismicClientMethod(proto.getAllByIDs, args);
 
+/**
+ * A hook that queries a document from the Prismic repository with a specific UID and Custom Type.
+ *
+ * @param documentType - The API ID of the document's Custom Type
+ * @param uid - UID of the document
+ * @param params - Parameters to filter, sort, and paginate results
+ *
+ * @returns The composable payload {@link ClientHookReturnType}
+ *
+ * @typeParam TDocument - Type of the Prismic document returned
+ *
+ * @remarks An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
+ * @see Underlying `@prismicio/client` method {@link proto.getByUID}
+ */
 export const usePrismicDocumentByUID = <
 	TDocument extends prismicT.PrismicDocument,
 >(
@@ -70,6 +166,20 @@ export const usePrismicDocumentByUID = <
 ): ClientHookReturnType<TDocument> =>
 	useStatefulPrismicClientMethod(proto.getByUID, args);
 
+/**
+ * A hook that queries a singleton document from the Prismic repository for a specific Custom Type.
+ *
+ * @param documentType - The API ID of the singleton Custom Type
+ * @param params - Parameters to filter, sort, and paginate results
+ *
+ * @returns The composable payload {@link ClientHookReturnType}
+ *
+ * @typeParam TDocument - Type of the Prismic document returned
+ *
+ * @remarks An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
+ * @see Underlying `@prismicio/client` method {@link proto.getSingle}
+ */
 export const useSinglePrismicDocument = <
 	TDocument extends prismicT.PrismicDocument,
 >(
@@ -80,6 +190,20 @@ export const useSinglePrismicDocument = <
 ): ClientHookReturnType<TDocument> =>
 	useStatefulPrismicClientMethod(proto.getSingle, args);
 
+/**
+ * A hook that queries documents from the Prismic repository for a specific Custom Type.
+ *
+ * @param documentType - The API ID of the Custom Type
+ * @param params - Parameters to filter, sort, and paginate results
+ *
+ * @returns The composable payload {@link ClientHookReturnType}
+ *
+ * @typeParam TDocument - Type of Prismic documents returned
+ *
+ * @remarks An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
+ * @see Underlying `@prismicio/client` method {@link proto.getByType}
+ */
 export const usePrismicDocumentsByType = <
 	TDocument extends prismicT.PrismicDocument,
 >(
@@ -90,6 +214,20 @@ export const usePrismicDocumentsByType = <
 ): ClientHookReturnType<prismic.Query<TDocument>> =>
 	useStatefulPrismicClientMethod(proto.getByType, args);
 
+/**
+ * A hook that queries all documents from the Prismic repository for a specific Custom Type.
+ *
+ * @param documentType - The API ID of the Custom Type
+ * @param params - Parameters to filter and sort results
+ *
+ * @returns The composable payload {@link ClientHookReturnType}
+ *
+ * @typeParam TDocument - Type of Prismic documents returned
+ *
+ * @remarks An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
+ * @see Underlying `@prismicio/client` method {@link proto.getAllByType}
+ */
 export const useAllPrismicDocumentsByType = <
 	TDocument extends prismicT.PrismicDocument,
 >(
@@ -100,6 +238,20 @@ export const useAllPrismicDocumentsByType = <
 ): ClientHookReturnType<TDocument[]> =>
 	useStatefulPrismicClientMethod(proto.getAllByType, args);
 
+/**
+ * A hook that queries documents from the Prismic repository with a specific tag.
+ *
+ * @param tag - The tag that must be included on a document
+ * @param params - Parameters to filter, sort, and paginate results
+ *
+ * @returns The composable payload {@link ClientHookReturnType}
+ *
+ * @typeParam TDocument - Type of Prismic documents returned
+ *
+ * @remarks An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
+ * @see Underlying `@prismicio/client` method {@link proto.getByTag}
+ */
 export const usePrismicDocumentsByTag = <
 	TDocument extends prismicT.PrismicDocument,
 >(
@@ -110,6 +262,20 @@ export const usePrismicDocumentsByTag = <
 ): ClientHookReturnType<prismic.Query<TDocument>> =>
 	useStatefulPrismicClientMethod(proto.getByTag, args);
 
+/**
+ * A hook that queries all documents from the Prismic repository with a specific tag.
+ *
+ * @param tag - The tag that must be included on a document
+ * @param params - Parameters to filter and sort results
+ *
+ * @returns The composable payload {@link ClientHookReturnType}
+ *
+ * @typeParam TDocument - Type of Prismic documents returned
+ *
+ * @remarks An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
+ * @see Underlying `@prismicio/client` method {@link proto.getAllByTag}
+ */
 export const useAllPrismicDocumentsByTag = <
 	TDocument extends prismicT.PrismicDocument,
 >(
@@ -120,6 +286,20 @@ export const useAllPrismicDocumentsByTag = <
 ): ClientHookReturnType<TDocument[]> =>
 	useStatefulPrismicClientMethod(proto.getAllByTag, args);
 
+/**
+ * A hook that queries documents from the Prismic repository with specific tags.
+ *
+ * @param tags - A list of tags that must be included on a document
+ * @param params - Parameters to filter, sort, and paginate results
+ *
+ * @returns The composable payload {@link ClientHookReturnType}
+ *
+ * @typeParam TDocument - Type of Prismic documents returned
+ *
+ * @remarks An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
+ * @see Underlying `@prismicio/client` method {@link proto.getByTags}
+ */
 export const usePrismicDocumentsByTags = <
 	TDocument extends prismicT.PrismicDocument,
 >(
@@ -130,6 +310,20 @@ export const usePrismicDocumentsByTags = <
 ): ClientHookReturnType<prismic.Query<TDocument>> =>
 	useStatefulPrismicClientMethod(proto.getByTags, args);
 
+/**
+ * A hook that queries all documents from the Prismic repository with specific tags.
+ *
+ * @param tags - A list of tags that must be included on a document
+ * @param params - Parameters to filter and sort results
+ *
+ * @returns The composable payload {@link ClientHookReturnType}
+ *
+ * @typeParam TDocument - Type of Prismic documents returned
+ *
+ * @remarks An additional `@prismicio/client` instance can be provided at `params.client`.
+ *
+ * @see Underlying `@prismicio/client` method {@link proto.getAllByTags}
+ */
 export const useAllPrismicDocumentsByTags = <
 	TDocument extends prismicT.PrismicDocument,
 >(