Skip to content

Commit de8a370

Browse files
author
Peter Janak
committed
Fixing jsdoc parsing of functions that are defined over multiple lines (Fixes #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/react-native#360 Github Author: Peter Janak <pjanak@nhl.com> Test Plan: Run the website
1 parent a2fa40f commit de8a370

2 files changed

Lines changed: 93 additions & 98 deletions

File tree

‎Libraries/CustomComponents/ListView/ListViewDataSource.js‎

Lines changed: 74 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -32,38 +32,6 @@ var invariant = require('invariant');
3232
var isEmpty = require('isEmpty');
3333
var warning = require('warning');
3434

35-
/**
36-
* ListViewDataSource - Provides efficient data processing and access to the
37-
* ListView component. A ListViewDataSource is created with functions for
38-
* extracting data from the input blob, and comparing elements (with default
39-
* implementations for convenience). The input blob can be as simple as an
40-
* array of strings, or an object with rows nested inside section objects.
41-
*
42-
* To update the data in the datasource, use `cloneWithRows` (or
43-
* `cloneWithRowsAndSections` if you care about sections). The data in the
44-
* data source is immutable, so you can't modify it directly. The clone methods
45-
* suck in the new data and compute a diff for each row so ListView knows
46-
* whether to re-render it or not.
47-
*
48-
* In this example, a component receives data in chunks, handled by
49-
* `_onDataArrived`, which concats the new data onto the old data and updates the
50-
* data source. We use `concat` to create a new array - mutating `this._data`,
51-
* e.g. with `this._data.push(newRowData)`, would be an error. `_rowHasChanged`
52-
* understands the shape of the row data and knows how to efficiently compare
53-
* it.
54-
*
55-
* getInitialState: function() {
56-
* var ds = new ListViewDataSource({rowHasChanged: this._rowHasChanged});
57-
* return {ds};
58-
* },
59-
* _onDataArrived(newData) {
60-
* this._data = this._data.concat(newData);
61-
* this.setState({
62-
* ds: this.state.ds.cloneWithRows(this._data)
63-
* });
64-
* }
65-
*/
66-
6735
function defaultGetRowData(
6836
dataBlob: any,
6937
sectionID: number | string,
@@ -88,15 +56,58 @@ type ParamType = {
8856
getSectionHeaderData: ?typeof defaultGetSectionHeaderData;
8957
}
9058

59+
/**
60+
* Provides efficient data processing and access to the
61+
* `ListView` component. A `ListViewDataSource` is created with functions for
62+
* extracting data from the input blob, and comparing elements (with default
63+
* implementations for convenience). The input blob can be as simple as an
64+
* array of strings, or an object with rows nested inside section objects.
65+
*
66+
* To update the data in the datasource, use `cloneWithRows` (or
67+
* `cloneWithRowsAndSections` if you care about sections). The data in the
68+
* data source is immutable, so you can't modify it directly. The clone methods
69+
* suck in the new data and compute a diff for each row so ListView knows
70+
* whether to re-render it or not.
71+
*
72+
* In this example, a component receives data in chunks, handled by
73+
* `_onDataArrived`, which concats the new data onto the old data and updates the
74+
* data source. We use `concat` to create a new array - mutating `this._data`,
75+
* e.g. with `this._data.push(newRowData)`, would be an error. `_rowHasChanged`
76+
* understands the shape of the row data and knows how to efficiently compare
77+
* it.
78+
*
79+
* ```
80+
* getInitialState: function() {
81+
* var ds = new ListViewDataSource({rowHasChanged: this._rowHasChanged});
82+
* return {ds};
83+
* },
84+
* _onDataArrived(newData) {
85+
* this._data = this._data.concat(newData);
86+
* this.setState({
87+
* ds: this.state.ds.cloneWithRows(this._data)
88+
* });
89+
* }
90+
* ```
91+
*/
92+
9193
class ListViewDataSource {
9294

9395
/**
94-
* @param {ParamType} params
95-
*
96-
* You can provide custom extraction and 'hasChanged' functions for section
96+
* You can provide custom extraction and `hasChanged` functions for section
9797
* headers and rows. If absent, data will be extracted with the
9898
* `defaultGetRowData` and `defaultGetSectionHeaderData` functions.
9999
*
100+
* The default extractor expects data of one of the following forms:
101+
*
102+
* { sectionID_1: { rowID_1: <rowData1>, ... }, ... }
103+
*
104+
* or
105+
*
106+
* [ [ <rowData1>, <rowData2>, ... ], ... ]
107+
*
108+
* The constructor takes in a params argument that can contain any of the
109+
* following:
110+
*
100111
* - getRowData(dataBlob, sectionID, rowID);
101112
* - getSectionHeaderData(dataBlob, sectionID);
102113
* - rowHasChanged(prevRowData, nextRowData);
@@ -125,14 +136,25 @@ class ListViewDataSource {
125136
}
126137

127138
/**
128-
* @param {object} dataBlob -- This is an arbitrary blob of data. An extractor
129-
* function was defined at construction time. The default extractor assumes
130-
* the data is a plain array or keyed object.
131-
*/
132-
cloneWithRows(
133-
dataBlob: Array<any> | {[key: string]: any},
134-
rowIdentities: ?Array<string>
135-
): ListViewDataSource {
139+
* Clones this `ListViewDataSource` with the specified `dataBlob` and
140+
* `rowIdentities`. The `dataBlob` is just an aribitrary blob of data. At
141+
* construction an extractor to get the interesting informatoin was defined
142+
* (or the default was used).
143+
*
144+
* The `rowIdentities` is is a 2D array of identifiers for rows.
145+
* ie. [['a1', 'a2'], ['b1', 'b2', 'b3'], ...]. If not provided, it's
146+
* assumed that the keys of the section data are the row identities.
147+
*
148+
* Note: This function does NOT clone the data in this data source. It simply
149+
* passes the functions defined at construction to a new data source with
150+
* the data specified. If you wish to maintain the existing data you must
151+
* handle merging of old and new data separately and then pass that into
152+
* this function as the `dataBlob`.
153+
*/
154+
cloneWithRows(
155+
dataBlob: Array<any> | {[key: string]: any},
156+
rowIdentities: ?Array<string>
157+
): ListViewDataSource {
136158
var rowIds = rowIdentities ? [rowIdentities] : null;
137159
if (!this._sectionHeaderHasChanged) {
138160
this._sectionHeaderHasChanged = () => false;
@@ -141,29 +163,20 @@ class ListViewDataSource {
141163
}
142164

143165
/**
144-
* @param {object} dataBlob -- This is an arbitrary blob of data. An extractor
145-
* function was defined at construction time. The default extractor assumes
146-
* the data is a nested array or keyed object of the form:
147-
*
148-
* { sectionID_1: { rowID_1: <rowData1>, ... }, ... }
149-
*
150-
* or
166+
* This performs the same function as the `cloneWithRows` function but here
167+
* you also specify what your `sectionIdentities` are. If you don't care
168+
* about sections you should safely be able to use `cloneWithRows`.
151169
*
152-
* [ [ <rowData1>, <rowData2>, ... ], ... ]
153-
*
154-
* @param {array} sectionIdentities -- This is an array of identifiers for
155-
* sections. ie. ['s1', 's2', ...]. If not provided, it's assumed that the
156-
* keys of dataBlob are the section identities.
157-
* @param {array} rowIdentities -- This is a 2D array of identifiers for rows.
158-
* ie. [['a1', 'a2'], ['b1', 'b2', 'b3'], ...]. If not provided, it's
159-
* assumed that the keys of the section data are the row identities.
170+
* `sectionIdentities` is an array of identifiers for sections.
171+
* ie. ['s1', 's2', ...]. If not provided, it's assumed that the
172+
* keys of dataBlob are the section identities.
160173
*
161174
* Note: this returns a new object!
162175
*/
163176
cloneWithRowsAndSections(
164-
dataBlob: any,
165-
sectionIdentities: ?Array<string>,
166-
rowIdentities: ?Array<Array<string>>
177+
dataBlob: any,
178+
sectionIdentities: ?Array<string>,
179+
rowIdentities: ?Array<Array<string>>
167180
): ListViewDataSource {
168181
invariant(
169182
typeof this._sectionHeaderHasChanged === 'function',
@@ -205,9 +218,6 @@ class ListViewDataSource {
205218
}
206219

207220
/**
208-
* @param {number} sectionIndex
209-
* @param {number} rowIndex
210-
*
211221
* Returns if the row is dirtied and needs to be rerendered
212222
*/
213223
rowShouldUpdate(sectionIndex: number, rowIndex: number): bool {
@@ -218,9 +228,6 @@ class ListViewDataSource {
218228
}
219229

220230
/**
221-
* @param {number} sectionIndex
222-
* @param {number} rowIndex
223-
*
224231
* Gets the data required to render the row.
225232
*/
226233
getRowData(sectionIndex: number, rowIndex: number): any {
@@ -234,8 +241,6 @@ class ListViewDataSource {
234241
}
235242

236243
/**
237-
* @param {number} index
238-
*
239244
* Gets the rowID at index provided if the dataSource arrays were flattened,
240245
* or null of out of range indexes.
241246
*/
@@ -252,8 +257,6 @@ class ListViewDataSource {
252257
}
253258

254259
/**
255-
* @param {number} index
256-
*
257260
* Gets the sectionID at index provided if the dataSource arrays were flattened,
258261
* or null for out of range indexes.
259262
*/
@@ -281,8 +284,6 @@ class ListViewDataSource {
281284
}
282285

283286
/**
284-
* @param {number} sectionIndex
285-
*
286287
* Returns if the section header is dirtied and needs to be rerendered
287288
*/
288289
sectionHeaderShouldUpdate(sectionIndex: number): bool {
@@ -293,8 +294,6 @@ class ListViewDataSource {
293294
}
294295

295296
/**
296-
* @param {number} sectionIndex
297-
*
298297
* Gets the data required to render the section header
299298
*/
300299
getSectionHeaderData(sectionIndex: number): any {

‎Libraries/Utilities/AlertIOS.js‎

Lines changed: 19 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -20,32 +20,28 @@ var DEFAULT_BUTTON = {
2020
};
2121

2222
/**
23-
* AlertIOS manages native iOS alerts, option sheets, and share dialogs
23+
* Launches an alert dialog with the specified title and message.
24+
*
25+
* Optionally provide a list of buttons. Tapping any button will fire the
26+
* respective onPress callback and dismiss the alert. By default, the only
27+
* button will be an 'OK' button
28+
*
29+
* The last button in the list will be considered the 'Primary' button and
30+
* it will appear bold.
31+
*
32+
* ```
33+
* AlertIOS.alert(
34+
* 'Foo Title',
35+
* 'My Alert Msg',
36+
* [
37+
* {text: 'Foo', onPress: () => console.log('Foo Pressed!')},
38+
* {text: 'Bar', onPress: () => console.log('Bar Pressed!')},
39+
* ]
40+
* )}
41+
* ```
2442
*/
2543

2644
class AlertIOS {
27-
28-
/**
29-
* Launches an alert dialog with the specified title and message.
30-
*
31-
* Optionally provide a list of buttons. Tapping any button will fire the
32-
* respective onPress callback and dismiss the alert. By default, the only
33-
* button will be an 'OK' button
34-
*
35-
* The last button in the list will be considered the 'Primary' button and
36-
* it will appear bold.
37-
*
38-
* ```
39-
* AlertIOS.alert(
40-
* 'Foo Title',
41-
* 'My Alert Msg',
42-
* [
43-
* {text: 'Foo', onPress: () => console.log('Foo Pressed!')},
44-
* {text: 'Bar', onPress: () => console.log('Bar Pressed!')},
45-
* ]
46-
* )}
47-
* ```
48-
*/
4945
static alert(
5046
title: ?string,
5147
message?: ?string,

0 commit comments

Comments
 (0)