docs: various edits (#72)

Author: shtaif

src/Iterate/index.tsx

@@ -6,7 +6,7 @@ import { useAsyncIter, type IterationResult } from '../useAsyncIter/index.js';
 export { Iterate, type IterateProps };
 
 /**
- * The `<Iterate>` helper component (also exported as `<It>`) is used to format and render an async
+ * The `<Iterate>` 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, can be seen as a {@link useAsyncIter `useAsyncIter`} hook in a component form,
@@ -46,15 +46,15 @@ export { Iterate, type IterateProps };
  * {@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
+ * Given an async iterable as the `value` prop, this component will iterate it and render every new
  * value that becomes available together with any possible completion or error it may run into.
- * If `value` is a plain (non async iterable) value, it will simply be rendered over as-is.
+ * If `value` is a plain (non async iterable) value, it will simply be rendered as-is.
  *
  * Whenever given `value` is changed from the previous one seen, `<Iterate>` will close the previous
  * if it was async iterable before proceeding to iterate the new `value`. Care should be taken to
- * avoid passing a constantly recreated iterable object across re-renders, e.g; by declaring it outside the component body or control __when__ it
- * 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.
+ * avoid passing a constantly recreated iterable object across re-renders, e.g; by declaring it outside
+ * the component body or by controlling __when__ it 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.
  *
  * ---
  *
@@ -141,7 +141,7 @@ type IterateProps<TVal, TInitialVal = undefined> =
 
 type IteratePropsWithRenderFunction<TVal, TInitialVal = undefined> = {
   /**
-   * The source value to iterate over, an async iterable or a plain (non async iterable) value.
+   * The source value to iterate over - an async iterable or a plain (non async iterable) value.
    */
   value: TVal;
   /**

src/IterateMulti/index.tsx

@@ -9,7 +9,7 @@ export { IterateMulti, type IterateMultiProps };
 // TODO: The initial values should be able to be given in function/s form, with consideration for iterable sources that could be added in dynamically.
 
 /**
- * The `<IterateMulti>` helper component (also exported as `<ItMulti>`) is used to combine and render
+ * The `<IterateMulti>` component (also exported as `<ItMulti>`) is used to combine and render
  * any number of async iterables (or plain non-iterable values) directly onto a piece of UI.
  *
  * It's similar to `<Iterate>`, only it works with any changeable number of async iterables or plain values

src/iterateFormatted/index.ts

@@ -14,8 +14,11 @@ import { type Iterate } from '../Iterate/index.js'; // eslint-disable-line @type
 export { iterateFormatted };
 
 /**
- * An optional utility to format an async iterable's values inline where its passed into
- * an other consuming component.
+ * A utility to inline-format an async iterable's values before passed into an other
+ * consuming component.
+ *
+ * Can be thought of as mapping an async iterable before being rendered/passed over in the same way
+ * you would commonly `.map(...)` an array before rendering/passing it over.
  *
  * @example
  * ```tsx
@@ -55,27 +58,26 @@ export { iterateFormatted };
  * This utility should come handy in places when you need a formatted (or _"mapped"_) version of
  * some existing async iterable before passing it as prop into an other component which consumes it
  * and you rather have the formatting logic right at the place in code of passing the prop instead
- * of far from it, having to perform the transformation using some `useMemo` call at the top of the
- * component.
+ * of having to perform the transformation using some `useMemo` call at the top of the component.
  *
  * The utility's method of operation is to be given a `source` and return from it a new transformed
  * async iterable object, attaching it with some special metadata that tells library tools like
- * {@link Iterate `<Iterate>`} and {@link useAsyncIter `useAsyncIter`} to bind the iteration process
- * to the same original base object. This way, the outer "formatted" iterable may be recreated repeatedly
- * without concerns of restarting the iteration process (as long as the `source` arg is consistently
- * passed the same base object).
+ * {@link Iterate `<Iterate>`} and {@link useAsyncIter `useAsyncIter`} that the original base object
+ * is what the iteration process should be bound to instead of the given object. This way, the
+ * resulting formatted iterable may be recreated repeatedly without concerns of restarting the
+ * iteration process (as long as `source` is passed the same base iterable consistently).
  *
  * `source` may have a current value property (at `.value.current` - per the `AsyncIterableSubject`
  * interface), in which case it will be formatted via `formatFn` in the same way like yielded values.
  *
- * If `source` is a plain value and not an async iterable, it will be passed to the given `formatFn`
+ * If `source` is a plain value and not an async iterable, it will be passed into the given `formatFn`
  * and returned on the spot.
  *
  * @template TIn The full type of the source input.
  * @template TRes The type of values resulting after formatting.
  *
  * @param source Any async iterable or plain value.
- * @param formatFn Function that performs formatting/mapping logic for each value of `source`
+ * @param formatFn Function that performs formatting/mapping logic for each value of `source`.
  *
  * @returns a transformed async iterable emitting every value of `source` after formatting.
  */

src/useAsyncIterState/index.ts

@@ -12,11 +12,13 @@ export { useAsyncIterState, type AsyncIterStateResult, type AsyncIterableChannel
 
 /**
  * Basically like {@link https://react.dev/reference/react/useState `React.useState`}, only that the value
- * is provided back __wrapped as an async iterable__.
+ * is provided back __wrapped in an async iterable__.
  *
- * This hook allows a component to declare and manage a piece of state while easily letting you control
- * what specifically area(s) within the UI should be bound to it (should re-render in reaction to changes
- * in it) - for example, if combined with one or more {@link Iterate `<Iterate>`}s.
+ * This hook allows a component to declare and manage a piece of state as an async iterable thus
+ * letting you easily control what specific places in the app UI tree should be bound to it,
+ * re-rendering in reaction to its changes (if used in conjunction with {@link Iterate `<Iterate>`}
+ * for example).
+
  *
  * @example
  * ```tsx
@@ -44,9 +46,9 @@ export { useAsyncIterState, type AsyncIterStateResult, type AsyncIterableChannel
  *
  * The returned async iterable can be passed over to any level down the component tree and rendered
  * using `<Iterate>`, `useAsyncIter`, and others. It also contains a `.value.current` property which shows
- * the current up to date state value at all times. Use this any time you need to read the immediate
+ * the current up to date state value at any time. Use this any time you need to read the immediate
  * current state (for example as part of side effect logic) rather than directly rendering it, since
- * for rendering you may simply iterate values as part of an `<Iterate>`.
+ * for rendering you may simply iterate the values as part of an `<Iterate>`.
  *
  * Returned also alongside the async iterable is a function for updating the state. Calling it with a new
  * value will cause the paired iterable to yield the updated state value as well as immediately set the
@@ -84,9 +86,7 @@ export { useAsyncIterState, type AsyncIterStateResult, type AsyncIterableChannel
  * }
  * ```
  *
- * The returned async iterable is a shared iterable - can be iterated by multiple consumers simultaneously
- * (e.g multiple {@link Iterate `<Iterate>`}s) and each would pick up the same yielded values and at the
- * same time.
+ * The returned async iterable is a shared iterable so that if iterated by multiple consumers simultaneously (e.g multiple {@link Iterate `<Iterate>`}s) then all would pick up the same yields at the same time.
  *
  * The returned async iterable is automatically closed on host component unmount.
  *
@@ -97,7 +97,7 @@ export { useAsyncIterState, type AsyncIterStateResult, type AsyncIterableChannel
  *
  * @param initialValue Any optional starting value for the state iterable's `.value.current` property, defaults to `undefined`. You can pass an actual value, or a function that returns a value (which the hook will call once during mounting).
  *
- * @returns a stateful async iterable and a function with which to yield an update, both maintain stable references across re-renders.
+ * @returns a stateful async iterable and a function for yielding an update. Both maintain stable references across re-renders.
  *
  * @see {@link Iterate `<Iterate>`}
  */