chore: add jsdocs and return types for hooks

Author: isekovanic

docusaurus/docs/reactnative/hooks/poll/use-poll-option-votes-pagination.mdx

@@ -3,7 +3,7 @@ id: use-poll-option-votes-pagination
 title: usePollOptionVotesPagination
 ---
 
-A hook that queries votes for a given option in a `Poll` and returns them in a paginated fashion. It can be used whenever we want to view all votes in a given `poll`, like in the [`PollOptionFullResults` component](../../ui-components/poll-option-full-results.mdx) for example.
+A hook that queries votes for a given option in a `Poll` and returns them in a paginated fashion. It can be used whenever we want to view all votes for an option in a given `poll`, like in the [`PollOptionFullResults` component](../../ui-components/poll-option-full-results.mdx) for example.
 
 ## Properties
 

package/src/components/Poll/hooks/usePollAnswersPagination.ts

@@ -11,10 +11,33 @@ export type UsePollAnswersPaginationParams = {
   paginationParams?: PollAnswersQueryParams;
 };
 
+export type UsePollAnswersReturnType = {
+  error: Error | undefined;
+  hasNextPage: boolean;
+  loading: boolean;
+  loadMore: () => void;
+  next: string | null | undefined;
+  pollAnswers: PollAnswer[];
+};
+
+/**
+ * A hook that queries answers for a given Poll and returns them in a paginated fashion.
+ * Should be used instead of the latest_answers property within the reactive state in the
+ * event that we need more than the top 10 answers. The returned property pollAnswers will
+ * automatically be updated and trigger a state change when paginating further.
+ *
+ * @param loadFirstPage {boolean} Signifies whether the first page should be automatically loaded whenever
+ * the hook is first called.
+ * @param paginationParams {PollAnswersQueryParams} The pagination params we might want to use for our custom
+ * needs when invoking the hook.
+ *
+ * @returns {UsePollAnswersReturnType} An object containing all of the needed pagination values as well as the
+ * answers.
+ **/
 export const usePollAnswersPagination = ({
   loadFirstPage = true,
   paginationParams,
-}: UsePollAnswersPaginationParams = {}) => {
+}: UsePollAnswersPaginationParams = {}): UsePollAnswersReturnType => {
   const { poll } = usePollContext();
   const { client } = useChatContext();
 

package/src/components/Poll/hooks/usePollOptionVotesPagination.ts

@@ -11,11 +11,37 @@ export type UsePollOptionVotesPaginationParams = {
   paginationParams?: PollOptionVotesQueryParams;
 };
 
+export type UsePollVotesReturnType = {
+  error: Error | undefined;
+  hasNextPage: boolean;
+  loading: boolean;
+  loadMore: () => void;
+  next: string | null | undefined;
+  votes: PollVote[];
+};
+
+/**
+ * A hook that queries votes for a given Poll and returns them in a paginated fashion.
+ * Should be used instead of the latest_votes_by_option property within the reactive state in the
+ * event that we need more than the top 10 votes for an option. The returned property votes will
+ * automatically be updated and trigger a state change when paginating further. Querying for votes
+ * can only be done on an option by option basis.
+ *
+ * @param option {PollOption} The option for which we want to load the votes.
+ * @param loadFirstPage {boolean} Signifies whether the first page should be automatically loaded whenever
+ * the hook is first called.
+ * @param paginationParams {PollOptionVotesQueryParams} The pagination params we might want to use for our custom
+ * needs when invoking the hook.
+ *
+ * @returns {UsePollVotesReturnType} An object containing all of the needed pagination values as well as the
+ * answers.
+ **/
+
 export const usePollOptionVotesPagination = ({
   loadFirstPage = true,
   option,
   paginationParams,
-}: UsePollOptionVotesPaginationParams) => {
+}: UsePollOptionVotesPaginationParams): UsePollVotesReturnType => {
   const { poll } = usePollContext();
   const { client } = useChatContext();
 

package/src/components/Poll/hooks/usePollState.ts

@@ -1,10 +1,13 @@
 import { useCallback } from 'react';
 
 import {
+  APIResponse,
+  CastVoteAPIResponse,
   PollAnswer,
   PollOption,
   PollState,
   PollVote,
+  UpdatePollAPIResponse,
   UserResponse,
   VotingVisibility,
 } from 'stream-chat';
@@ -32,6 +35,16 @@ export type UsePollStateSelectorReturnType = {
   voting_visibility: VotingVisibility | undefined;
 };
 
+export type UsePollStateReturnType<
+  StreamChatGenerics extends DefaultStreamChatGenerics = DefaultStreamChatGenerics,
+> = UsePollStateSelectorReturnType & {
+  addComment: (
+    answerText: string,
+  ) => Promise<APIResponse & CastVoteAPIResponse<StreamChatGenerics>>;
+  addOption: (optionText: string) => Promise<void>;
+  endVote: () => Promise<APIResponse & UpdatePollAPIResponse<StreamChatGenerics>>;
+};
+
 const selector = <StreamChatGenerics extends DefaultStreamChatGenerics = DefaultStreamChatGenerics>(
   nextValue: PollState<StreamChatGenerics>,
 ): UsePollStateSelectorReturnType => ({
@@ -51,7 +64,7 @@ const selector = <StreamChatGenerics extends DefaultStreamChatGenerics = Default
   voting_visibility: nextValue.voting_visibility,
 });
 
-export const usePollState = () => {
+export const usePollState = (): UsePollStateReturnType => {
   const { message, poll } = usePollContext();
   const {
     allow_answers,