Move new components out of `Experimental` directory

Summary: I think these are sufficiently baked. Also beef up comments.

Reviewed By: yungsters

Differential Revision: D4632604

fbshipit-source-id: 64ae6b240a05d62e418099f7403e1781f9b4717c

Libraries/CustomComponents/Lists/FlatList.js

@@ -53,7 +53,7 @@ type RequiredProps<ItemT> = {
    *     <TouchableOpacity/>
    *   );
    *   ...
-   *   <FlatList data={[{title: 'Title Text'}]} renderItem={this._renderItem} />
+   *   <FlatList data={[{title: 'Title Text', key: 'item1'}]} renderItem={this._renderItem} />
    *
    * Provides additional metadata like `index` if you need it.
    */
@@ -136,7 +136,7 @@ type OptionalProps<ItemT> = {
     nextInfo: {item: ItemT, index: number}
   ) => boolean,
   /**
-   * See ViewabilityHelper for flow type and comments.
+   * See ViewabilityHelper for flow type and further documentation.
    */
   viewabilityConfig?: ViewabilityConfig,
 };
@@ -160,14 +160,24 @@ type DefaultProps = typeof defaultProps;
  *  - Separator support.
  *  - Pull to Refresh
  *
- * If you need sticky section header support, use ListView.
+ * If you need sticky section header support, use ListView for now.
  *
  * Minimal Example:
  *
  *   <FlatList
- *     data={[{key: 'a', {key: 'b'}]}
+ *     data={[{key: 'a'}, {key: 'b'}]}
  *     renderItem={({item}) => <Text>{item.key}</Text>}
  *   />
+ *
+ * Some notes for all of the `VirtualizedList` based components:
+ * - Internal state is not preserved when content scrolls out of the render window. Make sure all
+ *   your data is captured in the item data or external stores like Flux, Redux, or Relay.
+ * - In order to constrain memory and enable smooth scrolling, content is rendered asynchronously
+ *   offscreen. This means it's possible to scroll faster than the fill rate ands momentarily see
+ *   blank content. This is a tradeoff that can be adjusted to suit the needs of each application,
+ *   and we are working on improving it behind the scenes.
+ * - By default, the list looks for a `key` prop on each item and uses that for the React key.
+ *   Alternatively, you can provide a custom keyExtractor prop.
  */
 class FlatList<ItemT> extends React.PureComponent<DefaultProps, Props<ItemT>, void> {
   static defaultProps: DefaultProps = defaultProps;

Libraries/CustomComponents/Lists/ViewabilityHelper.js

@@ -54,6 +54,9 @@ export type ViewabilityConfig = {|
 |};
 
 /**
+* A Utility class for calculating viewable items based on current metrics like scroll position and
+* layout.
+*
 * An item is said to be in a "viewable" state when any of the following
 * is true for longer than `minViewTime` milliseconds (after an interaction if `waitForInteraction`
 * is true):
@@ -78,10 +81,16 @@ class ViewabilityHelper {
     this._config = config;
   }
 
+  /**
+   * Cleanup, e.g. on unmount. Clears any pending timers.
+   */
   dispose() {
     this._timers.forEach(clearTimeout);
   }
 
+  /**
+   * Determines which items are viewable based on the current metrics and config.
+   */
   computeViewableItems(
     itemCount: number,
     scrollOffset: number,
@@ -135,6 +144,10 @@ class ViewabilityHelper {
     return viewableIndices;
   }
 
+  /**
+   * Figures out which items are viewable and how that has changed from before and calls
+   * `onViewableItemsChanged` as appropriate.
+   */
   onUpdate(
     itemCount: number,
     scrollOffset: number,
@@ -196,6 +209,9 @@ class ViewabilityHelper {
     }
   }
 
+  /**
+   * Records that an interaction has happened even if there has been no scroll.
+   */
   recordInteraction() {
     this._hasInteracted = true;
   }