Improve the documentation for ListView and ListViewDataSource

Summary:
What existing problem does the pull request solve?
My motivation was to improve the documentation for ListView and ListViewDataSource because I always have trouble remembering how they work and the documentation was lacking an example for `cloneWithRowsAndSections`

My PR does the following:
* add a note about how headers and footers are rendered on a horizontal ListView
* fix a typo in an example
* clarify that the sectionIdentities should match the keys or array indexes of the data source
* add an example of cloneWithRowsAndSections
* add notes on the return values of `getRowCount` and `getRowAndSectionCount`

n/a; documentation only

![screenshot of ListViewDataSource changes](https://cloud.githubusercontent.com/assets/580060/25768881/d339544a-31c1-11e7-88a1-5e60bc008500.png)
Closes #13811

Differential Revision: D5473192

Pulled By: hramos

fbshipit-source-id: f31fc6edfdeb8dff75d39bbcceda06fd839df934

Libraries/Lists/ListView/ListView.js

@@ -173,6 +173,8 @@ var ListView = createReactClass({
      * on every render pass. If they are expensive to re-render, wrap them
      * in StaticContainer or other mechanism as appropriate. Footer is always
      * at the bottom of the list, and header at the top, on every render pass.
+     * In a horizontal ListView, the header is rendered on the left and the
+     * footer on the right.
      */
     renderFooter: PropTypes.func,
     renderHeader: PropTypes.func,

Libraries/Lists/ListView/ListViewDataSource.js

@@ -62,7 +62,7 @@ type ParamType = {
  *
  * ```
  * getInitialState: function() {
- *   var ds = new ListViewDataSource({rowHasChanged: this._rowHasChanged});
+ *   var ds = new ListView.DataSource({rowHasChanged: this._rowHasChanged});
  *   return {ds};
  * },
  * _onDataArrived(newData) {
@@ -154,11 +154,19 @@ class ListViewDataSource {
    * you also specify what your `sectionIdentities` are. If you don't care
    * about sections you should safely be able to use `cloneWithRows`.
    *
-   * `sectionIdentities` is an array of identifiers for  sections.
-   * ie. ['s1', 's2', ...].  If not provided, it's assumed that the
+   * `sectionIdentities` is an array of identifiers for sections.
+   * ie. ['s1', 's2', ...].  The identifiers should correspond to the keys or array indexes
+   * of the data you wish to include.  If not provided, it's assumed that the
    * keys of dataBlob are the section identities.
    *
    * Note: this returns a new object!
+   *
+   * ```
+   * const dataSource = ds.cloneWithRowsAndSections({
+   *   addresses: ['row 1', 'row 2'],
+   *   phone_numbers: ['data 1', 'data 2'],
+   * }, ['phone_numbers']);
+   * ```
    */
   cloneWithRowsAndSections(
     dataBlob: any,
@@ -207,10 +215,20 @@ class ListViewDataSource {
     return newSource;
   }
 
+  /**
+   * Returns the total number of rows in the data source.
+   *
+   * If you are specifying the rowIdentities or sectionIdentities, then `getRowCount` will return the number of rows in the filtered data source.
+   */
   getRowCount(): number {
     return this._cachedRowCount;
   }
 
+  /**
+   * Returns the total number of rows in the data source (see `getRowCount` for how this is calculated) plus the number of sections in the data.
+   *
+   * If you are specifying the rowIdentities or sectionIdentities, then `getRowAndSectionCount` will return the number of rows & sections in the filtered data source.
+   */
   getRowAndSectionCount(): number {
     return this._cachedRowCount + this.sectionIdentities.length;
   }