Documents StyleSheet.flatten()

Summary:Indicates the purpose and an alternative use for the method too.
Closes https://github.com/facebook/react-native/pull/6662

Differential Revision: D3099823

Pulled By: vjeux

fb-gh-sync-id: 44633161a3df9b11d44afaed72fe6127f0b6bf7b
fbshipit-source-id: 44633161a3df9b11d44afaed72fe6127f0b6bf7b

Libraries/StyleSheet/StyleSheet.js

@@ -86,6 +86,45 @@ module.exports = {
    */
   hairlineWidth,
 
+  /**
+   * Flattens an array of style objects, into one aggregated style object.
+   * Alternatively, this method can be used to lookup IDs, returned by
+   * StyleSheet.register.
+   *
+   * > **NOTE**: Exercise caution as abusing this can tax you in terms of
+   * > optimizations.
+   * >
+   * > IDs enable optimizations through the bridge and memory in general. Refering
+   * > to style objects directly will deprive you of these optimizations.
+   *
+   * Example:
+   * ```
+   * var styles = StyleSheet.create({
+   *   listItem: {
+   *     flex: 1,
+   *     fontSize: 16,
+   *     color: 'white'
+   *   },
+   *   selectedListItem: {
+   *     color: 'green'
+   *   }
+   * });
+   *
+   * StyleSheet.flatten([styles.listItem, styles.selectedListItem]
+   * // returns { flex: 1, fontSize: 16, color: 'green' }
+   * ```
+   * Alternative use:
+   * ```
+   * StyleSheet.flatten(styles.listItem);
+   * // return { flex: 1, fontSize: 16, color: 'white' }
+   * // Simply styles.listItem would return its ID (number)
+   * ```
+   * This method internally uses `StyleSheetRegistry.getStyleByID(style)`
+   * to resolve style objects represented by IDs. Thus, an array of style
+   * objects (instances of StyleSheet.create), are individually resolved to,
+   * their respective objects, merged as one and then returned. This also explains
+   * the alternative use.
+   */
   flatten,
 
   /**