docs: add inline docs (#277)

# Documentation
- Improve descriptions and example labels in the readme file
- Add inline docs to public API

Author: LayZeeDK

README.md

@@ -28,7 +28,7 @@ A `RouterStore` service has the following public properties:
 | routeParams$: Observable<Params>                            | Select the current route parameters.       |
 | url$: Observable<string>                                    | Select the current URL.                    |
 | selectQueryParam<TValue>(param: string): Observable<TValue> | Select the specified query parameter.      |
-| selectRouteParam<TValue>(param: string): Observable<TValue> | Select the specified route paramter.       |
+| selectRouteParam<TValue>(param: string): Observable<TValue> | Select the specified route parameter.      |
 
 A `RouterStore` service is provided by using either `provideGlobalRouterStore` or `provideLocalRouterStore`.
 
@@ -40,10 +40,22 @@ other component-level services.
 
 ### Global router store
 
-An application-wide router store. Can be injected in any class. Provide
-in a root environment injector by using `provideGlobalRouterStore`.
+An application-wide router store that can be injected in any class. Use
+`provideGlobalRouterStore` to provide it in a root environment injector.
 
-Usage:
+Providing in a standalone Angular application:
+
+```typescript
+// main.ts
+// (...)
+import { provideGlobalRouterStore } from '@ngworker/router-component-store';
+
+bootstrapApplication(AppComponent, {
+  providers: [provideGlobalRouterStore()],
+}).catch((error) => console.error(error));
+```
+
+Providing in a classic Angular application:
 
 ```typescript
 // app.module.ts
@@ -57,6 +69,8 @@ import { provideGlobalRouterStore } from '@ngworker/router-component-store';
 export class AppModule {}
 ```
 
+Usage in service:
+
 ```typescript
 // hero.service.ts
 // (...)
@@ -66,12 +80,14 @@ import { RouterStore } from '@ngworker/router-component-store';
   providedIn: 'root',
 })
 export class HeroService {
-  activeHeroId$: Observable<string> = this.routerStore.selectQueryParam('id');
+  activeHeroId$: Observable<string> = this.routerStore.selectRouteParam('id');
 
   constructor(private routerStore: RouterStore) {}
 }
 ```
 
+Usage in component:
+
 ```typescript
 // hero-detail.component.ts
 // (...)
@@ -81,7 +97,7 @@ import { RouterStore } from '@ngworker/router-component-store';
   // (...)
 })
 export class HeroDetailComponent {
-  heroId$: Observable<string> = this.routerStore.selectQueryParam('id');
+  heroId$: Observable<string> = this.routerStore.selectRouteParam('id');
 
   constructor(private routerStore: RouterStore) {}
 }
@@ -93,7 +109,7 @@ A component-level router store. Can be injected in any directive, component,
 pipe, or component-level service. Explicitly provided in a component sub-tree
 using `Component.providers` or `Component.viewProviders`.
 
-Usage:
+Usage in component:
 
 ```typescript
 // hero-detail.component.ts
@@ -108,7 +124,7 @@ import {
   providers: [provideLocalRouterStore()],
 })
 export class HeroDetailComponent {
-  heroId$: Observable<string> = this.routerStore.selectQueryParam('id');
+  heroId$: Observable<string> = this.routerStore.selectRouteParam('id');
 
   constructor(private routerStore: RouterStore) {}
 }

packages/router-component-store/src/lib/@ngrx/router-store/minimal_serializer.ts

@@ -22,18 +22,57 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
 import { Injectable } from '@angular/core';
 import { ActivatedRouteSnapshot, RouterStateSnapshot } from '@angular/router';
 
+/**
+ * Contains the information about a route associated with a component loaded in
+ * an outlet at a particular moment in time. MinimalActivatedRouteSnapshot can
+ * also be used to traverse the router state tree.
+ */
 export interface MinimalActivatedRouteSnapshot {
+  /**
+   * The configuration used to match this route.
+   */
   readonly routeConfig: ActivatedRouteSnapshot['routeConfig'];
+  /**
+   * The URL segments matched by this route.
+   */
   readonly url: ActivatedRouteSnapshot['url'];
+  /**
+   * The matrix parameters scoped to this route.
+   */
   readonly params: ActivatedRouteSnapshot['params'];
+  /**
+   * The query parameters shared by all the routes.
+   */
   readonly queryParams: ActivatedRouteSnapshot['queryParams'];
+  /**
+   * The URL fragment shared by all the routes.
+   */
   readonly fragment: ActivatedRouteSnapshot['fragment'];
+  /**
+   * The static and resolved data of this route.
+   */
   readonly data: ActivatedRouteSnapshot['data'];
+  /**
+   * The outlet name of the route.
+   */
   readonly outlet: ActivatedRouteSnapshot['outlet'];
+  /**
+   * The first child of this route in the router state tree
+   */
   readonly firstChild?: MinimalActivatedRouteSnapshot;
+  /**
+   * The children of this route in the router state tree.
+   */
   readonly children: MinimalActivatedRouteSnapshot[];
 }
 

packages/router-component-store/src/lib/global-router-store/provide-global-router-store.ts

@@ -2,6 +2,36 @@ import { ClassProvider, Provider } from '@angular/core';
 import { RouterStore } from '../router-store';
 import { GlobalRouterStore } from './global-router-store';
 
+/**
+ * Provide an application-wide router store that can be injected in any class.
+ *
+ * Use this provider factory in a root environment injector.
+ *
+ * @returns The providers required for a global router store.
+ *
+ * @example
+ * // Providing in a standalone Angular application
+ * // main.ts
+ * // (...)
+ * import { provideGlobalRouterStore } from '@ngworker/router-component-store';
+ *
+ * bootstrapApplication(AppComponent, {
+ *   providers: [provideGlobalRouterStore()],
+ * }).catch((error) => console.error(error));
+ *
+ *
+ * @example
+ * // Providing in a classic Angular application
+ * // app.module.ts
+ * // (...)
+ * import { provideGlobalRouterStore } from '@ngworker/router-component-store';
+ *
+ * (@)NgModule({
+ *   // (...)
+ *   providers: [provideGlobalRouterStore()],
+ * })
+ * export class AppModule {}
+ */
 export function provideGlobalRouterStore(): Provider {
   const globalRouterStoreProvider: ClassProvider = {
     provide: RouterStore,

packages/router-component-store/src/lib/local-router-store/provide-local-router-store.ts

@@ -2,6 +2,35 @@ import { ClassProvider, Provider } from '@angular/core';
 import { RouterStore } from '../router-store';
 import { LocalRouterStore } from './local-router-store';
 
+/**
+ * Provide a component-level router store that can be injected in any directive,
+ * component, pipe, or component-level service.
+ *
+ * Use this provider factory in `Component.providers` or
+ * `Component.viewProviders` to make a local router store available to a
+ * component sub-tree.
+ *
+ * @returns The providers required for a local router store.
+ *
+ * @example
+ * // Providing and injecting in a component
+ * // hero-detail.component.ts
+ * // (...)
+ * import {
+ *   provideLocalRouterStore,
+ *   RouterStore,
+ * } from '@ngworker/router-component-store';
+ *
+ * (@)Component({
+ *   // (...)
+ *   providers: [provideLocalRouterStore()],
+ * })
+ * export class HeroDetailComponent {
+ *   heroId$: Observable<string> = this.routerStore.selectQueryParam('id');
+ *
+ *   constructor(private routerStore: RouterStore) {}
+ * }
+ */
 export function provideLocalRouterStore(): Provider {
   const localRouterStoreProvider: ClassProvider = {
     provide: RouterStore,

packages/router-component-store/src/lib/router-store.ts

@@ -3,14 +3,76 @@ import { Data, Params } from '@angular/router';
 import { Observable } from 'rxjs';
 import { MinimalActivatedRouteSnapshot } from './@ngrx/router-store/minimal_serializer';
 
+/**
+ * An Angular Router-connecting NgRx component store.
+ *
+ * A `RouterStore` service is provided by using either
+ * `provideGlobalRouterStore` or `provideLocalRouterStore`.
+ *
+ * The _global_ `RouterStore` service is provided in a root environment injector
+ * and is never destroyed but can be injected in any class.
+ *
+ * A _local_ `RouterStore` requires a component-level provider, follows the
+ * lifecycle of that component, and can be injected in declarables as well as
+ * other component-level services.
+ *
+ * @example
+ * // Usage in a component
+ * // hero-detail.component.ts
+ * // (...)
+ * import { RouterStore } from '@ngworker/router-component-store';
+ *
+ * (@)Component({
+ *   // (...)
+ * })
+ * export class HeroDetailComponent {
+ *   heroId$: Observable<string> = this.routerStore.selectRouteParam('id');
+ *
+ *   constructor(private routerStore: RouterStore) {}
+ * }
+ */
 @Injectable()
 export abstract class RouterStore {
+  /**
+   * Select the current route.
+   */
   abstract readonly currentRoute$: Observable<MinimalActivatedRouteSnapshot>;
+  /**
+   * Select the current route fragment.
+   */
   abstract readonly fragment$: Observable<string | null>;
+  /**
+   * Select the current route query parameters.
+   */
   abstract readonly queryParams$: Observable<Params>;
+  /**
+   * Select the current route data.
+   */
   abstract readonly routeData$: Observable<Data>;
+  /**
+   * Select the current route parameters.
+   */
   abstract readonly routeParams$: Observable<Params>;
+  /**
+   * Select the current URL.
+   */
   abstract readonly url$: Observable<string>;
+  /**
+   * Select the specified query parameter.
+   *
+   * @param param The name of the query parameter.
+   *
+   * @example <caption>Usage</caption>
+   * const order$ = routerStore.selectQueryParam('order');
+   */
   abstract selectQueryParam<TValue>(param: string): Observable<TValue>;
+  /**
+   * Select the specified route parameter.
+   *
+   * @param param The name of the route parameter.
+   *
+   * @example <caption>Usage</caption>
+   * const id$ = routerStore.selectRouteParam('id');
+   */
   abstract selectRouteParam<TValue>(param: string): Observable<TValue>;
 }