add examples that demonstrate how to use mergeItem, multiMerge, multi…

Summary:Thanks for submitting a pull request! Please provide enough information so that others can review your pull request:

(You can skip this if you're fixing a typo or adding an app to the Showcase.)

Explain the **motivation** for making this change. What existing problem does the pull request solve?

it wasn't clear how to use various methods such as mergeItem, multiMerge, etc, so after figuring it out I thought it would be useful to provide clear examples for others.

Example: When "Adding a function to do X", explain why it is necessary to have a way to do X.

**Test plan (required)**

Demonstrate the code is solid. Example: The exact commands you ran and their output, screenshots / videos if the pull request changes UI.

Make sure tests pass on both Travis and Circle CI.

**Code formatting**

See the simple [style guide](https://github.com/facebook/react-native/blob/master/CONTRIBUTING.md#style-guide).

…Set, multiGet, and multiRemove
Closes https://github.com/facebook/react-native/pull/6423

Differential Revision: D3048502

Pulled By: vjeux

fb-gh-sync-id: dfe13c6a88fa9d3e7646b5ecaa5f594bfaba8271
shipit-source-id: dfe13c6a88fa9d3e7646b5ecaa5f594bfaba8271

Libraries/Storage/AsyncStorage.js

@@ -105,6 +105,30 @@ var AsyncStorage = {
   /**
    * Merges existing value with input value, assuming they are stringified json.
    * Returns a `Promise` object. Not supported by all native implementations.
+   *
+   * Example:
+   * ```javascript
+   * let UID123_object = {
+   *  name: 'Chris',
+   *  age: 30,
+   *  traits: {hair: 'brown', eyes: 'brown'},
+   * };
+
+   // need only define what will be added or updated
+   * let UID123_delta = {
+   *  age: 31,
+   *  traits: {eyes: 'blue', shoe_size: 10}
+   * };
+
+   * AsyncStorage.setItem(store_key, JSON.stringify(UID123_object), () => {
+   *   AsyncStorage.mergeItem('UID123', JSON.stringify(UID123_delta), () => {
+   *     AsyncStorage.getItem('UID123', (err, result) => {
+   *       console.log(result);
+   *       // => {'name':'Chris','age':31,'traits':{'shoe_size':10,'hair':'brown','eyes':'blue'}}
+   *     });
+   *   });
+   * });
+   * ```
    */
   mergeItem: function(
     key: string,
@@ -144,6 +168,8 @@ var AsyncStorage = {
 
   /**
    * Gets *all* keys known to the app, for all callers, libraries, etc. Returns a `Promise` object.
+   *
+   * Example: see multiGet for example
    */
   getAllKeys: function(callback?: ?(error: ?Error, keys: ?Array<string>) => void): Promise {
     return new Promise((resolve, reject) => {
@@ -201,6 +227,19 @@ var AsyncStorage = {
    * matches the input format of multiSet. Returns a `Promise` object.
    *
    *   multiGet(['k1', 'k2'], cb) -> cb([['k1', 'val1'], ['k2', 'val2']])
+   *
+   * Example:
+   * ```javascript
+   * AsyncStorage.getAllKeys((err, keys) => {
+   *   AsyncStorage.multiGet(keys, (err, stores) => {
+   *    stores.map((result, i, store) => {
+   *      // get at each store's key/value so you can work with it
+   *      let key = store[i][0];
+   *      let value = store[i][1];
+   *     });
+   *   });
+   * });
+   * ```
    */
   multiGet: function(
     keys: Array<string>,
@@ -243,6 +282,8 @@ var AsyncStorage = {
    * the output of multiGet, e.g. Returns a `Promise` object.
    *
    *   multiSet([['k1', 'val1'], ['k2', 'val2']], cb);
+   *
+   * Example: see multiMerge for an example
    */
   multiSet: function(
     keyValuePairs: Array<Array<string>>,
@@ -263,6 +304,15 @@ var AsyncStorage = {
 
   /**
    * Delete all the keys in the `keys` array. Returns a `Promise` object.
+   *
+   * Example:
+   * ```javascript
+   * let keys = ['k1', 'k2'];
+   * AsyncStorage.multiRemove(keys, (err) => {
+   *   // keys k1 & k2 removed, if they existed
+   *   // do most stuff after removal (if you want)
+   * });
+   * ```
    */
   multiRemove: function(
     keys: Array<string>,
@@ -286,6 +336,52 @@ var AsyncStorage = {
    * json. Returns a `Promise` object.
    *
    * Not supported by all native implementations.
+   *
+   * Example:
+   * ```javascript
+   // first user, initial values
+   * let UID234_object = {
+   *  name: 'Chris',
+   *  age: 30,
+   *  traits: {hair: 'brown', eyes: 'brown'},
+   * };
+
+   * // first user, delta values
+   * let UID234_delta = {
+   *  age: 31,
+   *  traits: {eyes: 'blue', shoe_size: 10},
+   * };
+
+   * // second user, initial values
+   * let UID345_object = {
+   *  name: 'Marge',
+   *  age: 25,
+   *  traits: {hair: 'blonde', eyes: 'blue'},
+   * };
+
+   * // second user, delta values
+   * let UID345_delta = {
+   *  age: 26,
+   *  traits: {eyes: 'green', shoe_size: 6},
+   * };
+
+   * let multi_set_pairs   = [['UID234', JSON.stringify(UID234_object)], ['UID345', JSON.stringify(UID345_object)]]
+   * let multi_merge_pairs = [['UID234', JSON.stringify(UID234_delta)], ['UID345', JSON.stringify(UID345_delta)]]
+
+   * AsyncStorage.multiSet(multi_set_pairs, (err) => {
+   *   AsyncStorage.multiMerge(multi_merge_pairs, (err) => {
+   *     AsyncStorage.multiGet(['UID234','UID345'], (err, stores) => {
+   *       stores.map( (result, i, store) => {
+   *         let key = store[i][0];
+   *         let val = store[i][1];
+   *         console.log(key, val);
+   *         // => UID234 {"name":"Chris","age":31,"traits":{"shoe_size":10,"hair":"brown","eyes":"blue"}}
+   *         // => UID345 {"name":"Marge","age":26,"traits":{"shoe_size":6,"hair":"blonde","eyes":"green"}}
+   *       });
+   *     });
+   *   });
+   * });
+   * ```
    */
   multiMerge: function(
     keyValuePairs: Array<Array<string>>,