improve

elastic · Jun 18, 2020 · 8607a27 · 8607a27
1 parent cd9163b
commit 8607a27
Show file tree

Hide file tree

Showing 3 changed files with 17 additions and 19 deletions.
diff --git a/src/plugins/kibana_utils/public/state_sync/index.ts b/src/plugins/kibana_utils/public/state_sync/index.ts
@@ -21,19 +21,19 @@
  * State syncing utilities are a set of helpers for syncing your application state
  * with URL or browser storage.
  *
- * They are designed to work together with state containers ({@link StateContainer}). But state containers are not required.
+ * They are designed to work together with {@link https://github.com/elastic/kibana/tree/master/src/plugins/kibana_utils/docs/state_containers | state containers}. But state containers are not required.
  *
  * State syncing utilities include:
  *
- * - {@link syncState} util which:
- * - Subscribes to state changes and pushes them to state storage.
- * - Optionally subscribes to state storage changes and pushes them to state.
- * - Two types of storage compatible with `syncState`:
- * - {@link IKbnUrlStateStorage} - Serializes state and persists it to URL's query param in rison or hashed format.
+ * *{@link syncState} util which:
+ *   * Subscribes to state changes and pushes them to state storage.
+ *   * Optionally subscribes to state storage changes and pushes them to state.
+ *   * Two types of storage compatible with `syncState`:
+ *   * {@link IKbnUrlStateStorage} - Serializes state and persists it to URL's query param in rison or hashed format.
  * Listens for state updates in the URL and pushes them back to state.
- * - {@link ISessionStorageStateStorage} - Serializes state and persists it to browser storage.
+ *   * {@link ISessionStorageStateStorage} - Serializes state and persists it to browser storage.
  *
- * Refer {@link https://github.com/elastic/kibana/tree/master/src/plugins/kibana_utils/docs/state_sync | here} for a complete guide and examples
+ * Refer {@link https://github.com/elastic/kibana/tree/master/src/plugins/kibana_utils/docs/state_sync | here} for a complete guide and examples.
  * @packageDocumentation
  */
 

diff --git a/src/plugins/kibana_utils/public/state_sync/state_sync.ts b/src/plugins/kibana_utils/public/state_sync/state_sync.ts
@@ -52,11 +52,12 @@ export interface ISyncStateRef<stateStorage extends IStateStorage = IStateStorag
 /**
  * Utility for syncing application state wrapped in state container
  * with some kind of storage (e.g. URL)
- * Refer {@link https://github.com/elastic/kibana/tree/master/src/plugins/kibana_utils/docs/state_sync | here} for a complete guide and examples
+ *
+ * Go {@link https://github.com/elastic/kibana/tree/master/src/plugins/kibana_utils/docs/state_sync | here} for a complete guide and examples.
  *
  * @example
  *
- * 1. the simplest use case
+ * the simplest use case
  * ```ts
  * const stateStorage = createKbnUrlStateStorage();
  * syncState({
@@ -67,7 +68,7 @@ export interface ISyncStateRef<stateStorage extends IStateStorage = IStateStorag
  * ```
  *
  * @example
- * 2. conditionally configuring sync strategy
+ * conditionally configuring sync strategy
  * ```ts
  * const stateStorage = createKbnUrlStateStorage({useHash: config.get('state:stateContainerInSessionStorage')})
  * syncState({
@@ -78,7 +79,7 @@ export interface ISyncStateRef<stateStorage extends IStateStorage = IStateStorag
  * ```
  *
  * @example
- * 3. implementing custom sync strategy
+ * implementing custom sync strategy
  * ```ts
  * const localStorageStateStorage = {
  *   set: (storageKey, state) => localStorage.setItem(storageKey, JSON.stringify(state)),
@@ -92,7 +93,7 @@ export interface ISyncStateRef<stateStorage extends IStateStorage = IStateStorag
  * ```
  *
  * @example
- * 4. Transform state before serialising
+ * transform state before serialising
  *  Useful for:
  *  * Migration / backward compatibility
  *  * Syncing part of state
@@ -110,11 +111,6 @@ export interface ISyncStateRef<stateStorage extends IStateStorage = IStateStorag
  * });
  * ```
  *
- * @remarks
- *
- * 1. It is responsibility of consumer to make sure that initial app state and storage are in sync before starting syncing
- *    No initial sync happens when syncState() is called
- *
  * @param - syncing config {@link IStateSyncConfig}
  * @returns - {@link ISyncStateRef}
  * @public

diff --git a/...s/kibana_utils/public/state_sync/state_sync_state_storage/create_kbn_url_state_storage.ts b/...s/kibana_utils/public/state_sync/state_sync_state_storage/create_kbn_url_state_storage.ts
@@ -29,13 +29,15 @@ import {
 
 /**
  * KbnUrlStateStorage is a state storage for {@link syncState} utility which:
+ *
  * 1. Keeps state in sync with the URL.
  * 2. Serializes data and stores it in the URL in one of the supported formats:
  *   * Rison encoded.
  *   * Hashed URL: In URL we store only the hash from the serialized state, but the state itself is stored in sessionStorage. See kibana's advanced option for more context state:storeInSessionStorage
  * 3. Takes care of listening to the URL updates and notifies state about the updates.
  * 4. Takes care of batching URL updates to prevent redundant browser history records.
- * {@link https://github.com/elastic/kibana/blob/master/src/plugins/kibana_utils/docs/state_sync/storages/kbn_url_storage.md | GUIDE}
+ *
+ * {@link https://github.com/elastic/kibana/blob/master/src/plugins/kibana_utils/docs/state_sync/storages/kbn_url_storage.md | Refer to this guide for more info}
  * @public
  */
 export interface IKbnUrlStateStorage extends IStateStorage {