Skip to content

Commit

Permalink
Fixing jsdoc parsing of functions that are defined over multiple lines (
Browse files Browse the repository at this point in the history 
Fixes facebook#410)

Summary:
As it was implemented, the jsdoc parser would look only the first non-blank line immediately preceding a function declaration. However, the line that was set as the beginning of a function declaration was where the opening bracket (`{`) was. This is insufficient for functions whose definitions span multiple lines. For example, this declaration would not find the comments above it:

```
/**
 * Clones rows
 **/
cloneWithRows(
       dataBlob: Array<any> | {[key: string]: any},
       rowIdentities: ?Array<string>
   ): ListViewDataSource {
...
}
```

With this change, the parser will first check if we have a closing parenthesis. If we do and don't have a matching open parenthesis we continue moving up the lines until we find it. Then we set previous line to be the line before that, the true beginning of the function declaration.
Closes facebook#360
Github Author: Peter Janak <pjanak@nhl.com>

Test Plan: Run the website
  • Loading branch information
Peter Janak committed Apr 4, 2015
1 parent 0bb6b2f commit e239feb
Show file tree
Hide file tree
Showing 2 changed files with 93 additions and 98 deletions.
149 changes: 74 additions & 75 deletions Libraries/CustomComponents/ListView/ListViewDataSource.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,38 +32,6 @@ var invariant = require('invariant');
var isEmpty = require('isEmpty');
var warning = require('warning');

/**
* ListViewDataSource - Provides efficient data processing and access to the
* ListView component. A ListViewDataSource is created with functions for
* extracting data from the input blob, and comparing elements (with default
* implementations for convenience). The input blob can be as simple as an
* array of strings, or an object with rows nested inside section objects.
*
* To update the data in the datasource, use `cloneWithRows` (or
* `cloneWithRowsAndSections` if you care about sections). The data in the
* data source is immutable, so you can't modify it directly. The clone methods
* suck in the new data and compute a diff for each row so ListView knows
* whether to re-render it or not.
*
* In this example, a component receives data in chunks, handled by
* `_onDataArrived`, which concats the new data onto the old data and updates the
* data source. We use `concat` to create a new array - mutating `this._data`,
* e.g. with `this._data.push(newRowData)`, would be an error. `_rowHasChanged`
* understands the shape of the row data and knows how to efficiently compare
* it.
*
* getInitialState: function() {
* var ds = new ListViewDataSource({rowHasChanged: this._rowHasChanged});
* return {ds};
* },
* _onDataArrived(newData) {
* this._data = this._data.concat(newData);
* this.setState({
* ds: this.state.ds.cloneWithRows(this._data)
* });
* }
*/

function defaultGetRowData(
dataBlob: any,
sectionID: number | string,
Expand All @@ -88,15 +56,58 @@ type ParamType = {
getSectionHeaderData: ?typeof defaultGetSectionHeaderData;
}

/**
* Provides efficient data processing and access to the
* `ListView` component. A `ListViewDataSource` is created with functions for
* extracting data from the input blob, and comparing elements (with default
* implementations for convenience). The input blob can be as simple as an
* array of strings, or an object with rows nested inside section objects.
*
* To update the data in the datasource, use `cloneWithRows` (or
* `cloneWithRowsAndSections` if you care about sections). The data in the
* data source is immutable, so you can't modify it directly. The clone methods
* suck in the new data and compute a diff for each row so ListView knows
* whether to re-render it or not.
*
* In this example, a component receives data in chunks, handled by
* `_onDataArrived`, which concats the new data onto the old data and updates the
* data source. We use `concat` to create a new array - mutating `this._data`,
* e.g. with `this._data.push(newRowData)`, would be an error. `_rowHasChanged`
* understands the shape of the row data and knows how to efficiently compare
* it.
*
* ```
* getInitialState: function() {
* var ds = new ListViewDataSource({rowHasChanged: this._rowHasChanged});
* return {ds};
* },
* _onDataArrived(newData) {
* this._data = this._data.concat(newData);
* this.setState({
* ds: this.state.ds.cloneWithRows(this._data)
* });
* }
* ```
*/

class ListViewDataSource {

/**
* @param {ParamType} params
*
* You can provide custom extraction and 'hasChanged' functions for section
* You can provide custom extraction and `hasChanged` functions for section
* headers and rows. If absent, data will be extracted with the
* `defaultGetRowData` and `defaultGetSectionHeaderData` functions.
*
* The default extractor expects data of one of the following forms:
*
* { sectionID_1: { rowID_1: <rowData1>, ... }, ... }
*
* or
*
* [ [ <rowData1>, <rowData2>, ... ], ... ]
*
* The constructor takes in a params argument that can contain any of the
* following:
*
* - getRowData(dataBlob, sectionID, rowID);
* - getSectionHeaderData(dataBlob, sectionID);
* - rowHasChanged(prevRowData, nextRowData);
Expand Down Expand Up @@ -125,14 +136,25 @@ class ListViewDataSource {
}

/**
* @param {object} dataBlob -- This is an arbitrary blob of data. An extractor
* function was defined at construction time. The default extractor assumes
* the data is a plain array or keyed object.
*/
cloneWithRows(
dataBlob: Array<any> | {[key: string]: any},
rowIdentities: ?Array<string>
): ListViewDataSource {
* Clones this `ListViewDataSource` with the specified `dataBlob` and
* `rowIdentities`. The `dataBlob` is just an aribitrary blob of data. At
* construction an extractor to get the interesting informatoin was defined
* (or the default was used).
*
* The `rowIdentities` is is a 2D array of identifiers for rows.
* ie. [['a1', 'a2'], ['b1', 'b2', 'b3'], ...]. If not provided, it's
* assumed that the keys of the section data are the row identities.
*
* Note: This function does NOT clone the data in this data source. It simply
* passes the functions defined at construction to a new data source with
* the data specified. If you wish to maintain the existing data you must
* handle merging of old and new data separately and then pass that into
* this function as the `dataBlob`.
*/
cloneWithRows(
dataBlob: Array<any> | {[key: string]: any},
rowIdentities: ?Array<string>
): ListViewDataSource {
var rowIds = rowIdentities ? [rowIdentities] : null;
if (!this._sectionHeaderHasChanged) {
this._sectionHeaderHasChanged = () => false;
Expand All @@ -141,29 +163,20 @@ class ListViewDataSource {
}

/**
* @param {object} dataBlob -- This is an arbitrary blob of data. An extractor
* function was defined at construction time. The default extractor assumes
* the data is a nested array or keyed object of the form:
*
* { sectionID_1: { rowID_1: <rowData1>, ... }, ... }
*
* or
* This performs the same function as the `cloneWithRows` function but here
* you also specify what your `sectionIdentities` are. If you don't care
* about sections you should safely be able to use `cloneWithRows`.
*
* [ [ <rowData1>, <rowData2>, ... ], ... ]
*
* @param {array} sectionIdentities -- This is an array of identifiers for
* sections. ie. ['s1', 's2', ...]. If not provided, it's assumed that the
* keys of dataBlob are the section identities.
* @param {array} rowIdentities -- This is a 2D array of identifiers for rows.
* ie. [['a1', 'a2'], ['b1', 'b2', 'b3'], ...]. If not provided, it's
* assumed that the keys of the section data are the row identities.
* `sectionIdentities` is an array of identifiers for sections.
* ie. ['s1', 's2', ...]. If not provided, it's assumed that the
* keys of dataBlob are the section identities.
*
* Note: this returns a new object!
*/
cloneWithRowsAndSections(
dataBlob: any,
sectionIdentities: ?Array<string>,
rowIdentities: ?Array<Array<string>>
dataBlob: any,
sectionIdentities: ?Array<string>,
rowIdentities: ?Array<Array<string>>
): ListViewDataSource {
invariant(
typeof this._sectionHeaderHasChanged === 'function',
Expand Down Expand Up @@ -205,9 +218,6 @@ class ListViewDataSource {
}

/**
* @param {number} sectionIndex
* @param {number} rowIndex
*
* Returns if the row is dirtied and needs to be rerendered
*/
rowShouldUpdate(sectionIndex: number, rowIndex: number): bool {
Expand All @@ -218,9 +228,6 @@ class ListViewDataSource {
}

/**
* @param {number} sectionIndex
* @param {number} rowIndex
*
* Gets the data required to render the row.
*/
getRowData(sectionIndex: number, rowIndex: number): any {
Expand All @@ -234,8 +241,6 @@ class ListViewDataSource {
}

/**
* @param {number} index
*
* Gets the rowID at index provided if the dataSource arrays were flattened,
* or null of out of range indexes.
*/
Expand All @@ -252,8 +257,6 @@ class ListViewDataSource {
}

/**
* @param {number} index
*
* Gets the sectionID at index provided if the dataSource arrays were flattened,
* or null for out of range indexes.
*/
Expand Down Expand Up @@ -281,8 +284,6 @@ class ListViewDataSource {
}

/**
* @param {number} sectionIndex
*
* Returns if the section header is dirtied and needs to be rerendered
*/
sectionHeaderShouldUpdate(sectionIndex: number): bool {
Expand All @@ -293,8 +294,6 @@ class ListViewDataSource {
}

/**
* @param {number} sectionIndex
*
* Gets the data required to render the section header
*/
getSectionHeaderData(sectionIndex: number): any {
Expand Down
42 changes: 19 additions & 23 deletions Libraries/Utilities/AlertIOS.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,32 +20,28 @@ var DEFAULT_BUTTON = {
};

/**
* AlertIOS manages native iOS alerts, option sheets, and share dialogs
* Launches an alert dialog with the specified title and message.
*
* Optionally provide a list of buttons. Tapping any button will fire the
* respective onPress callback and dismiss the alert. By default, the only
* button will be an 'OK' button
*
* The last button in the list will be considered the 'Primary' button and
* it will appear bold.
*
* ```
* AlertIOS.alert(
* 'Foo Title',
* 'My Alert Msg',
* [
* {text: 'Foo', onPress: () => console.log('Foo Pressed!')},
* {text: 'Bar', onPress: () => console.log('Bar Pressed!')},
* ]
* )}
* ```
*/

class AlertIOS {

/**
* Launches an alert dialog with the specified title and message.
*
* Optionally provide a list of buttons. Tapping any button will fire the
* respective onPress callback and dismiss the alert. By default, the only
* button will be an 'OK' button
*
* The last button in the list will be considered the 'Primary' button and
* it will appear bold.
*
* ```
* AlertIOS.alert(
* 'Foo Title',
* 'My Alert Msg',
* [
* {text: 'Foo', onPress: () => console.log('Foo Pressed!')},
* {text: 'Bar', onPress: () => console.log('Bar Pressed!')},
* ]
* )}
* ```
*/
static alert(
title: ?string,
message?: ?string,
Expand Down

0 comments on commit e239feb

Please sign in to comment.