docs: Adding docs

mnasyrov · Aug 15, 2021 · 8397a6c · 8397a6c
1 parent a5e5c92
commit 8397a6c
Show file tree

Hide file tree

Showing 7 changed files with 115 additions and 40 deletions.
diff --git a/packages/rx-effects-react/README.md b/packages/rx-effects-react/README.md
@@ -12,7 +12,7 @@ Reactive state and effect management with RxJS. Tooling for React.js.
 
 ## Documentation
 
-- [General docs](https://github.com/mnasyrov/rx-effects#readme)
+- [Main docs](https://github.com/mnasyrov/rx-effects#readme)
 - [API docs](docs/README.md)
 
 ## Installation
@@ -23,8 +23,49 @@ npm install rx-effects rx-effects-react --save
 
 ## Usage
 
-`// TODO: Documentation`
+The package provides utility hooks to bind the core [RxEffects][rx-effects/docs]
+to React components and hooks:
 
-## License
+- [`useConst`](docs/README.md#useconst) – keeps the value as a constant between renders.
+- [`useController`](docs/README.md#usecontroller) – creates an ad-hoc controller by the factory and destroys it on unmounting.
+- [`useObservable`](docs/README.md#useobservable) – returns a value provided by `source$` observable.
+- [`useObserver`](docs/README.md#useobserver) – subscribes the provided observer or `next` handler on `source$` observable.
+- [`useSelector`](docs/README.md#useselector) – returns a value provided by `source$` observable.
+- [`useStateQuery`](docs/README.md#usestatequery) – returns a value which is provided by the query.
 
-[MIT](LICENSE)
+Example:
+
+```tsx
+// pizzaShopComponent.tsx
+
+import React, { FC, useEffect } from 'react';
+import { useConst, useObservable, useStateQuery } from 'rx-effects-react';
+import { createPizzaShopController } from './pizzaShop';
+
+export const PizzaShopComponent: FC = () => {
+  // Creates the controller and destroy it on unmounting the component
+  const controller = useConst(() => createPizzaShopController());
+  useEffect(() => controller.destroy, [controller]);
+
+  // The same creation can be achieved by using `useController()` helper:
+  // const controller = useController(createPizzaShopController);
+
+  // Using the controller
+  const { ordersQuery, addPizza, removePizza, submitCart, submitState } =
+    controller;
+
+  // Subscribing to state data and the effect stata
+  const orders = useStateQuery(ordersQuery);
+  const isPending = useStateQuery(submitState.pending);
+  const submitError = useObservable(submitState.error$, undefined);
+
+  // Actual rendering should be here.
+  return null;
+};
+```
+
+---
+
+[rx-effects/docs]: packages/rx-effects/README.md
+
+&copy; 2021 [Mikhail Nasyrov](https://github.com/mnasyrov), [MIT license](./LICENSE)
diff --git a/packages/rx-effects-react/docs/README.md b/packages/rx-effects-react/docs/README.md
@@ -7,6 +7,7 @@ rx-effects-react
 ### Functions
 
 - [useConst](README.md#useconst)
+- [useController](README.md#usecontroller)
 - [useObservable](README.md#useobservable)
 - [useObserver](README.md#useobserver)
 - [useSelector](README.md#useselector)
@@ -40,7 +41,40 @@ If the factory is provided, it is called only once.
 
 #### Defined in
 
-[useConst.ts:12](https://github.com/mnasyrov/rx-effects/blob/f3195d1/packages/rx-effects-react/src/useConst.ts#L12)
+[rx-effects-react/src/useConst.ts:12](https://github.com/mnasyrov/rx-effects/blob/a5e5c92/packages/rx-effects-react/src/useConst.ts#L12)
+
+---
+
+### useController
+
+▸ **useController**<`T`\>(`factory`, `dependencies?`): `T`
+
+Creates an ad-hoc controller by the factory and destroys it on unmounting a
+component.
+
+The factory is not part of the dependencies by default. It should be
+included explicitly when it is needed.
+
+#### Type parameters
+
+| Name | Type                                                                          |
+| :--- | :---------------------------------------------------------------------------- |
+| `T`  | extends `Readonly`<{ `destroy`: () => `void` } & `Record`<`string`, `any`\>\> |
+
+#### Parameters
+
+| Name            | Type        | Description                                            |
+| :-------------- | :---------- | :----------------------------------------------------- |
+| `factory`       | () => `T`   | a controller factory                                   |
+| `dependencies?` | `unknown`[] | array of hook dependencies to recreate the controller. |
+
+#### Returns
+
+`T`
+
+#### Defined in
+
+[rx-effects-react/src/useController.ts:17](https://github.com/mnasyrov/rx-effects/blob/a5e5c92/packages/rx-effects-react/src/useController.ts#L17)
 
 ---
 
@@ -79,15 +113,15 @@ const value = useObservable<string>(source$, undefined);
 
 #### Defined in
 
-[useObservable.ts:19](https://github.com/mnasyrov/rx-effects/blob/f3195d1/packages/rx-effects-react/src/useObservable.ts#L19)
+[rx-effects-react/src/useObservable.ts:19](https://github.com/mnasyrov/rx-effects/blob/a5e5c92/packages/rx-effects-react/src/useObservable.ts#L19)
 
 ---
 
 ### useObserver
 
 ▸ **useObserver**<`T`\>(`source$`, `observerOrNext`): `Subscription`
 
-Subscribes the provided observer or `next` handler on the source.
+Subscribes the provided observer or `next` handler on `source$` observable.
 
 This hook allows to do fine handling of the source observable.
 
@@ -119,7 +153,7 @@ useObserver(source$, observer);
 
 #### Defined in
 
-[useObserver.ts:21](https://github.com/mnasyrov/rx-effects/blob/f3195d1/packages/rx-effects-react/src/useObserver.ts#L21)
+[rx-effects-react/src/useObserver.ts:21](https://github.com/mnasyrov/rx-effects/blob/a5e5c92/packages/rx-effects-react/src/useObserver.ts#L21)
 
 ---
 
@@ -165,15 +199,15 @@ const value = useSelector<{ data: Record<string, string> }>(
 
 #### Defined in
 
-[useSelector.ts:26](https://github.com/mnasyrov/rx-effects/blob/f3195d1/packages/rx-effects-react/src/useSelector.ts#L26)
+[rx-effects-react/src/useSelector.ts:26](https://github.com/mnasyrov/rx-effects/blob/a5e5c92/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.
+Returns a value which is provided by the query.
 
 #### Type parameters
 
@@ -193,4 +227,4 @@ Provides the current and future values which are provided by the query.
 
 #### Defined in
 
-[useStateQuery.ts:9](https://github.com/mnasyrov/rx-effects/blob/f3195d1/packages/rx-effects-react/src/useStateQuery.ts#L9)
+[rx-effects-react/src/useStateQuery.ts:9](https://github.com/mnasyrov/rx-effects/blob/a5e5c92/packages/rx-effects-react/src/useStateQuery.ts#L9)
diff --git a/packages/rx-effects-react/src/useController.ts b/packages/rx-effects-react/src/useController.ts
@@ -5,8 +5,8 @@ import { useEffect, useMemo } from 'react';
 import { Controller } from 'rx-effects';
 
 /**
- * Creates a controller by the factory and destroys it on unmounting a
- * component
+ * Creates an ad-hoc controller by the factory and destroys it on unmounting a
+ * component.
  *
  * The factory is not part of the dependencies by default. It should be
  * included explicitly when it is needed.

diff --git a/packages/rx-effects-react/src/useObserver.ts b/packages/rx-effects-react/src/useObserver.ts
@@ -3,7 +3,7 @@ import { Observable, Observer, Subscription } from 'rxjs';
 import { useConst } from './useConst';
 
 /**
- * Subscribes the provided observer or `next` handler on the source.
+ * Subscribes the provided observer or `next` handler on `source$` observable.
  *
  * This hook allows to do fine handling of the source observable.
  *

diff --git a/packages/rx-effects-react/src/useStateQuery.ts b/packages/rx-effects-react/src/useStateQuery.ts
@@ -2,7 +2,7 @@ import { useEffect, useState } from 'react';
 import { StateQuery } from 'rx-effects';
 
 /**
- * Provides the current and future values which are provided by the query.
+ * Returns a value which is provided by the query.
  *
  * @param query – a query for a value
  */

diff --git a/packages/rx-effects/README.md b/packages/rx-effects/README.md
@@ -12,7 +12,7 @@ Reactive state and effect management with RxJS.
 
 ## Documentation
 
-- [General docs](https://github.com/mnasyrov/rx-effects#readme)
+- [Main docs](https://github.com/mnasyrov/rx-effects#readme)
 - [API docs](docs/README.md)
 
 ## Installation
@@ -25,6 +25,6 @@ npm install rx-effects --save
 
 `// TODO: Documentation`
 
-## License
+---
 
-[MIT](LICENSE)
+&copy; 2021 [Mikhail Nasyrov](https://github.com/mnasyrov), [MIT license](./LICENSE)