docs: Adding API docs

mnasyrov · Aug 15, 2021 · 9cd5bf6 · 9cd5bf6
1 parent f3195d1
commit 9cd5bf6
Show file tree

Hide file tree

Showing 3 changed files with 105 additions and 71 deletions.
diff --git a/README.md b/README.md
@@ -10,20 +10,6 @@ Reactive state and effect management with RxJS.
 [![licence](https://img.shields.io/github/license/mnasyrov/rx-effects.svg)](https://github.com/mnasyrov/rx-effects/blob/master/LICENSE)
 [![Coverage Status](https://coveralls.io/repos/github/mnasyrov/rx-effects/badge.svg?branch=main)](https://coveralls.io/github/mnasyrov/rx-effects?branch=main)
 
-## Table of Contents
-
-<!-- toc -->
-
-- [Overview](#overview)
-  - [Features](#features)
-  - [Packages](#packages)
-- [Usage](#usage)
-  - [Installation](#installation)
-  - [Concepts](#concepts)
-  - [Example](#example)
-
-<!-- tocstop -->
-
 ## Overview
 
 The library provides a way to describe business and application logic using MVC-like architecture. Core elements include actions and effects, states and stores. All of them are optionated and can be used separately. The core package is framework-agnostic and can be used in different cases: libraries, server apps, web, SPA and micro-frontends apps.

diff --git a/packages/rx-effects-react/docs/README.md b/packages/rx-effects-react/docs/README.md
@@ -18,6 +18,10 @@ rx-effects-react
 
 ▸ **useConst**<`T`\>(`initialValue`): `T`
 
+Keeps the value as a constant between renders of a component.
+
+If the factory is provided, it is called only once.
+
 #### Type parameters
 
 | Name |
@@ -26,24 +30,35 @@ rx-effects-react
 
 #### Parameters
 
-| Name           | Type             |
-| :------------- | :--------------- |
-| `initialValue` | () => `T` \| `T` |
+| Name           | Type             | Description                        |
+| :------------- | :--------------- | :--------------------------------- |
+| `initialValue` | () => `T` \| `T` | a value or a factory for the value |
 
 #### Returns
 
 `T`
 
 #### Defined in
 
-[useConst.ts:5](https://github.com/mnasyrov/rx-effects/blob/d1c09fc/packages/rx-effects-react/src/useConst.ts#L5)
+[useConst.ts:12](https://github.com/mnasyrov/rx-effects/blob/f3195d1/packages/rx-effects-react/src/useConst.ts#L12)
 
 ---
 
 ### useObservable
 
 ▸ **useObservable**<`T`\>(`source$`, `initialValue`, `compare?`): `T`
 
+Returns a value provided by `source$`.
+
+The hook returns the initial value and subscribes on the `source$`. After
+that, the hook returns values which are provided by the source.
+
+**`example`**
+
+```ts
+const value = useObservable<string>(source$, undefined);
+```
+
 #### Type parameters
 
 | Name |
@@ -52,26 +67,39 @@ rx-effects-react
 
 #### Parameters
 
-| Name           | Type                                |
-| :------------- | :---------------------------------- |
-| `source$`      | `Observable`<`T`\>                  |
-| `initialValue` | `T`                                 |
-| `compare?`     | (`v1`: `T`, `v2`: `T`) => `boolean` |
+| Name           | Type                                | Description                                  |
+| :------------- | :---------------------------------- | :------------------------------------------- |
+| `source$`      | `Observable`<`T`\>                  | an observable for values                     |
+| `initialValue` | `T`                                 | th first value which is returned by the hook |
+| `compare?`     | (`v1`: `T`, `v2`: `T`) => `boolean` | -                                            |
 
 #### Returns
 
 `T`
 
 #### Defined in
 
-[useObservable.ts:4](https://github.com/mnasyrov/rx-effects/blob/d1c09fc/packages/rx-effects-react/src/useObservable.ts#L4)
+[useObservable.ts:19](https://github.com/mnasyrov/rx-effects/blob/f3195d1/packages/rx-effects-react/src/useObservable.ts#L19)
 
 ---
 
 ### useObserver
 
 ▸ **useObserver**<`T`\>(`source$`, `observerOrNext`): `Subscription`
 
+Subscribes the provided observer or `next` handler on the source.
+
+This hook allows to do fine handling of the source observable.
+
+**`example`**
+
+```ts
+const observer = useCallback((nextValue) => {
+  logger.log(nextValue);
+}, []);
+useObserver(source$, observer);
+```
+
 #### Type parameters
 
 | Name |
@@ -80,24 +108,40 @@ rx-effects-react
 
 #### Parameters
 
-| Name             | Type                                                     |
-| :--------------- | :------------------------------------------------------- |
-| `source$`        | `Observable`<`T`\>                                       |
-| `observerOrNext` | `Partial`<`Observer`<`T`\>\> \| (`value`: `T`) => `void` |
+| Name             | Type                                                     | Description                  |
+| :--------------- | :------------------------------------------------------- | :--------------------------- |
+| `source$`        | `Observable`<`T`\>                                       | an observable                |
+| `observerOrNext` | `Partial`<`Observer`<`T`\>\> \| (`value`: `T`) => `void` | `Observer` or `next` handler |
 
 #### Returns
 
 `Subscription`
 
 #### Defined in
 
-[useObserver.ts:5](https://github.com/mnasyrov/rx-effects/blob/d1c09fc/packages/rx-effects-react/src/useObserver.ts#L5)
+[useObserver.ts:21](https://github.com/mnasyrov/rx-effects/blob/f3195d1/packages/rx-effects-react/src/useObserver.ts#L21)
 
 ---
 
 ### useSelector
 
-▸ **useSelector**<`S`, `R`\>(`state$`, `initialState`, `selector`, `compare?`): `R`
+▸ **useSelector**<`S`, `R`\>(`source$`, `initialValue`, `selector`, `comparator?`): `R`
+
+Returns a value provided by `source$`.
+
+The hook returns the initial value and subscribes on the `source$`. After
+that, the hook returns values which are provided by the source.
+
+**`example`**
+
+```ts
+const value = useSelector<{ data: Record<string, string> }>(
+  source$,
+  undefined,
+  (state) => state.data,
+  (data1, data2) => data1.key === data2.key,
+);
+```
 
 #### Type parameters
 
@@ -108,27 +152,29 @@ rx-effects-react
 
 #### Parameters
 
-| Name           | Type                                |
-| :------------- | :---------------------------------- |
-| `state$`       | `Observable`<`S`\>                  |
-| `initialState` | `S`                                 |
-| `selector`     | (`state`: `S`) => `R`               |
-| `compare`      | (`v1`: `R`, `v2`: `R`) => `boolean` |
+| Name           | Type                                | Description                                                                |
+| :------------- | :---------------------------------- | :------------------------------------------------------------------------- |
+| `source$`      | `Observable`<`S`\>                  | an observable for values                                                   |
+| `initialValue` | `S`                                 | th first value which is returned by the hook                               |
+| `selector`     | (`state`: `S`) => `R`               | a transform function for getting a derived value based on the source value |
+| `comparator`   | (`v1`: `R`, `v2`: `R`) => `boolean` | a comparator for previous and next values                                  |
 
 #### Returns
 
 `R`
 
 #### Defined in
 
-[useSelector.ts:4](https://github.com/mnasyrov/rx-effects/blob/d1c09fc/packages/rx-effects-react/src/useSelector.ts#L4)
+[useSelector.ts:26](https://github.com/mnasyrov/rx-effects/blob/f3195d1/packages/rx-effects-react/src/useSelector.ts#L26)
 
 ---
 
 ### useStateQuery
 
 ▸ **useStateQuery**<`T`\>(`query`): `T`
 
+Provides the current and future values which are provided by the query.
+
 #### Type parameters
 
 | Name |
@@ -137,14 +183,14 @@ rx-effects-react
 
 #### Parameters
 
-| Name    | Type               |
-| :------ | :----------------- |
-| `query` | `StateQuery`<`T`\> |
+| Name    | Type               | Description           |
+| :------ | :----------------- | :-------------------- |
+| `query` | `StateQuery`<`T`\> | – a query for a value |
 
 #### Returns
 
 `T`
 
 #### Defined in
 
-[useStateQuery.ts:4](https://github.com/mnasyrov/rx-effects/blob/d1c09fc/packages/rx-effects-react/src/useStateQuery.ts#L4)
+[useStateQuery.ts:9](https://github.com/mnasyrov/rx-effects/blob/f3195d1/packages/rx-effects-react/src/useStateQuery.ts#L9)