docs: various JSDocs blocks edits (#38)

Author: shtaif

src/Iterate/index.tsx

@@ -4,45 +4,45 @@ import { useAsyncIter, type IterationResult } from '../useAsyncIter/index.js';
 export { Iterate, type IterateProps };
 
 /**
- * The `<Iterate>` helper component (importable also as `<It>`) is used to format and render an async iterable
- * (or a plain non-iterable value) directly onto a piece of UI.
+ * The `<Iterate>` helper component (also exported as `<It>`) is used to format and render an async
+ * iterable (or a plain non-iterable value) directly onto a piece of UI.
  *
- * Essentially wraps a single {@link useAsyncIter `useAsyncIter`} hook call into a component
+ * Essentially, can be seen as a {@link useAsyncIter `useAsyncIter`} hook in a component form,
  * conveniently.
  *
  * _Illustration:_
  *
  * ```tsx
- * import { Iterate } from 'react-async-iterators';
+ * import { It } from 'react-async-iterators';
  *
  * function SelfUpdatingTodoList(props) {
  *   return (
  *     <div>
  *       <h2>My TODOs</h2>
  *
  *       <div>
- *         Last TODO was completed at: <Iterate>{props.lastCompletedTodoDate}</Iterate>
+ *         Last TODO was completed at: <It>{props.lastCompletedTodoDate}</It>
  *       </div>
  *
  *       <ul>
- *         <Iterate value={props.todosAsyncIter}>
+ *         <It value={props.todosAsyncIter}>
  *           {({ value: todos }) =>
  *             todos?.map(todo =>
  *               <li key={todo.id}>{todo.text}</li>
  *             )
  *           }
- *         </Iterate>
+ *         </It>
  *       </ul>
  *     </div>
  *   );
  * }
  * ```
  *
- * `<Iterate>` may be preferable over {@link useAsyncIter `useAsyncIter`} typically as the UI area
- * it re-renders can be expressively confined to the minimum necessary, saving unrelated elements
- * within UI of a larger component from re-evaluating. On the other hand, the
- * counterpart {@link useAsyncIter `useAsyncIter`} being a hook has to re-render the entire
- * component output for every new value.
+ * `<Iterate>` may be preferable over the {@link useAsyncIter `useAsyncIter`} counterpart typically as
+ * the UI area it re-renders within a component tree can be expressly confined to the necessary
+ * minimum, saving any other unrelated elements from re-evaluation - while on the other hand
+ * {@link useAsyncIter `useAsyncIter`} being a hook it has to re-render an entire
+ * component's output for every new value.
  *
  * Given an async iterable as the `value` prop, this component will iterate it and render each new
  * value that becomes available together with any possible completion or error it may run into.
@@ -54,15 +54,16 @@ export { Iterate, type IterateProps };
  * should be recreated with React's [`useMemo`](https://react.dev/reference/react/useMemo).
  * `<Iterate>` will automatically close its iterated iterable as soon as it gets unmounted.
  *
+ * ---
+ *
  * @template TVal The type of values yielded by the passed iterable or otherwise type of the passed plain value itself.
  * @template TInitialVal The type of the initial value, defaults to `undefined`.
  *
  * @param props Props for `<Iterate>`. See {@link IterateProps `IterateProps`}.
  *
- * @returns A React node that updates its contents in response to each next yielded value automatically as
- * formatted by the function passed as `children` (or in the absent of, just the yielded values as-are).
+ * @returns A React node that re-renders itself with each yielded value, completion or error, and formatted by the child render function passed into `children` (or just the yielded value as-is in the absent of it).
  *
- * @see {@link IterationResult}
+ * @see {@link IterationResult `IterationResult`}
  *
  * @example
  * ```tsx
@@ -129,7 +130,7 @@ function Iterate<TVal, TInitialVal = undefined>(props: IterateProps<TVal, TIniti
  * 1. Providing a render function as `children` to dynamically format each state of the iteration.
  * 2. Providing an async iterable as `children` to render the values of the async iterable (or plain value) directly as are.
  *
- * @template TVal The type of values yielded by the passed iterable or otherwise type of the passed plain value itself.
+ * @template TVal The type of the input async iterable or plain value.
  * @template TInitialVal The type of the initial value, defaults to `undefined`.
  */
 type IterateProps<TVal, TInitialVal = undefined> =
@@ -142,11 +143,13 @@ type IteratePropsWithRenderFunction<TVal, TInitialVal = undefined> = {
    */
   value: TVal;
   /**
-   * An optional initial value, defaults to `undefined`.
+   * An optional initial value, defaults to `undefined`. Will be the value provided inside the child
+   * render function when `<Iterate>` first renders on being mounted and while it's pending its first
+   * value to be yielded.
    */
   initialValue?: TInitialVal;
   /**
-   * A render function that is called for each iteration state and returns something to render
+   * A render function that is called for each step of the iteration, returning something to render
    * out of it.
    *
    * @param nextIterationState - The current state of the iteration, including the yielded value, whether iteration is complete, any associated error, etc. (see {@link IterationResult `IterationResult`})

src/useAsyncIterMulti/index.ts

@@ -15,87 +15,64 @@ export { useAsyncIterMulti, type IterationResult, type IterationResultSet };
  * `useAsyncIterMulti` hooks up multiple async iterables to your component and its lifecycle, letting
  * additional async iterables be added or removed on the go.
  *
- * Similar to `useAsyncIter`, only it works with zero or more async iterables and plain values instead of
- * a single one.
+ * It's similar to `useAsyncIter`, only it works with any changeable number of async iterables or
+ * plain values instead of a single one.
+ *
+ * ---
+ *
+ * _Illustration:_
  *
  * @example
  * ```tsx
  * import { useAsyncIterMulti } from 'react-async-iterators';
  *
- * const wordGen = (async function* () {
- *   const words = ['Hello', 'React', 'Async', 'Iterators'];
- *   for (const word of words) {
- *     await new Promise(resolve => setTimeout(resolve, 1500));
- *     yield word;
- *   }
- * })();
- *
- * const fruitGen = (async function* () {
- *   const sets = [
- *     ['Peach', 'Mango', 'Orange'],
- *     ['Apple', 'Pear', 'Guyava'],
- *     ['Watermelon', 'Kiwi', 'Grapes'],
- *   ];
- *   for (const fruits of sets) {
- *     await new Promise(resolve => setTimeout(resolve, 2000));
- *     yield fruits;
- *   }
- * })();
- *
  * function MyComponent() {
- *   const [currentWords, currentFruits] = useAsyncIterMulti([wordGen, fruitGen]);
+ *   const [nextNum, nextStr, nextArr] = useAsyncIterMulti([numberIter, stringIter, arrayIter], {
+ *     initialValues: [0, '', []]
+ *   });
  *
- *   return (
- *     <div>
- *       <h2>
- *         Current word:
- *         {currentWords.pendingFirst
- *           ? 'Loading fruits...'
- *           : currentWords.error
- *           ? `Error: ${currentWords.error}`
- *           : currentWords.done
- *           ? `Done (last value: ${currentWords.value})`
- *           : `Value: ${currentWords.value}`}
- *       </h2>
- *       <ul>
- *         {currentFruits.pendingFirst
- *           ? 'Loading words...'
- *           : currentFruits.value.map(fruit => (
- *             <div key={fruit.name}>{fruit.name}</div>
- *           ))}
- *       </ul>
- *     </div>
- *   );
+ *   nextNum.value; // Current value of `numberIter`
+ *   nextStr.value; // Current value of `stringIter`
+ *   nextArr.value; // Current value of `arrayIter`
+ *   nextNum.done; // Whether iteration of `numberIter` ended
+ *   nextStr.done; // Whether iteration of `stringIter` ended
+ *   nextArr.done; // Whether iteration of `arrayIter` ended
+ *
+ *   // ...
  * }
  * ```
  *
  * Given an array of async iterables for `inputs`, this hook will iterate over all of them concurrently,
  * updating (re-rendering) the host component whenever any yields a value, completes, or errors outs -
- * each time returning a combined array of all their current individual states, corresponding to their
- * original positions in the given `inputs`.
+ * each time returning an array combining all their current individual states, in correspondence to
+ * their original positions they were given in on `inputs`.
+ *
  * `inputs` may also be mixed with plain (non async iterable) values, in which case they'll simply be
  * returned as-are, coinciding along current values of other async iterables.
- * This can enable components that could seamlessly handle _"static"_ as well as _"changing"_ values
+ * This can enable components that can work seamlessly with either _"static"_ and _"changing"_ values
  * and props.
  *
  * The hook initializes and maintains its iteration process with each async iterable object as long as
  * that same object remains present in `inputs` arrays across subsequent updates. Changing the position
  * of such object in the array on a consequent call will __not__ close its current running iteration - it
- * will only change the position its result would appear at in the returned array.
+ * will only change the position its result appears at in the returned array.
  * Care should be taken therefore to not unintentionally recreate the given iterables on every render,
- * by e.g; declaring an iterable outside the component body, control __when__ it should be recreated
- * with React's [`useMemo`](https://react.dev/reference/react/useMemo) or alternatively use the library's
- * {@link iterateFormatted `iterateFormatted`} util for a formatted version of an iterable which
- * preserves its identity.
+ * by e.g; declaring an iterable outside the component body, controling __when__ it should be recreated
+ * with React's [`useMemo`](https://react.dev/reference/react/useMemo) or preferably use the library's
+ * {@link iterateFormatted `iterateFormatted`} util for formatting an iterable's values while preserving
+ * its identity.
+ *
  * Whenever `useAsyncIterMulti` detects that one or more previously present async iterables have
  * disappeared from the `inputs` array, it will close their iteration processes.
- * On component unmount, the hook will also ensure closing all actively iterated async iterables.
+ * On component unmount, the hook will ensure closing all active iterated async iterables entirely.
  *
  * The array returned from `useAsyncIterMulti` contains all the individual most recent states of all
  * actively iterated objects and/or plain values from the current `inputs` (including each's most recent
  * value, who's completed, etc. - see {@link IterationResultSet `IterationResultSet`}).
  *
- * @template TValues The type of the set of all plain or async iterable input values an array.
+ * ---
+ *
+ * @template TValues The array/tuple type of the input set of async iterable or plain values.
  * @template TInitValues The type of all initial values corresponding to types of `TValues`.
  *
  * @param inputs An array of zero or more async iterable or plain values (mixed).
@@ -108,7 +85,65 @@ export { useAsyncIterMulti, type IterationResult, type IterationResultSet };
  *
  * @example
  * ```tsx
- * // Using `useAsyncIterMulti` with a dynamically-changing amount of inputs:
+ * import { useAsyncIterMulti } from 'react-async-iterators';
+ *
+ * function MyDemo() {
+ *   const [currentWords, currentFruits] = useAsyncIterMulti(
+ *     [wordGen, fruitGen],
+ *     { initialValues: ['', []] }
+ *   );
+ *
+ *   return (
+ *     <div>
+ *       Current word:
+ *       <h2>
+ *         {currentWords.pendingFirst
+ *           ? 'Loading words...'
+ *           : currentWords.error
+ *           ? `Error: ${currentWords.error}`
+ *           : currentWords.done
+ *           ? `Done (last value: ${currentWords.value})`
+ *           : `Value: ${currentWords.value}`}
+ *       </h2>
+ *
+ *       Fruits:
+ *       <ul>
+ *         {currentFruits.pendingFirst
+ *           ? 'Loading fruits...'
+ *           : currentFruits.value.map(fruit => (
+ *             <li key={fruit.icon}>{fruit.icon}</li>
+ *           ))}
+ *       </ul>
+ *     </div>
+ *   );
+ * }
+ *
+ * const wordGen = (async function* () {
+ *   const words = ['Hello', 'React', 'Async', 'Iterators'];
+ *   for (const word of words) {
+ *     await new Promise(resolve => setTimeout(resolve, 1250));
+ *     yield word;
+ *   }
+ * })();
+ *
+ * const fruitGen = (async function* () {
+ *   const sets = [
+ *     [{ icon: '🍑' }, { icon: '🥭' }, { icon: '🍊' }],
+ *     [{ icon: '🍏' }, { icon: '🍐' }, { icon: '🍋' }],
+ *     [{ icon: '🍉' }, { icon: '🥝' }, { icon: '🍇' }],
+ *   ];
+ *   for (const fruits of sets) {
+ *     await new Promise(resolve => setTimeout(resolve, 2000));
+ *     yield fruits;
+ *   }
+ * })();
+ * ```
+ *
+ * ---
+ *
+ * @example
+ * ```tsx
+ * // Using `useAsyncIterMulti` with a dynamically-changed amount of inputs:
  *
  * import { useState } from 'react';
  * import { useAsyncIterMulti, type MaybeAsyncIterable } from 'react-async-iterators';