opendev/gerrit
Code Issues Proposed changes

Downport "Replace deprecated require-jsdoc, valid-jsdoc with jsdoc plugin for eslint"

Browse Source 
Enabled and fixed for `check-alignment`, `implements-on-classes`,
`newline-after-description`, `require-param-name`, `require-param-type`,
`require-returns-type` and `valid-types`.

Change-Id: I493b498d81d5f8d908bb45de37de9c9ef956f7d8
This commit is contained in:
Tao Zhou
2019-12-17 09:59:28 +01:00
committed by Thomas Draebing
parent 3445b3d2c4
commit 25673abbae
75 changed files with 278 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
package.json
View File

@@ -7,6 +7,7 @@
"eslint": "^6.6.0",
"eslint-config-google": "^0.13.0",
"eslint-plugin-html": "^6.0.0",
"eslint-plugin-jsdoc": "^18.4.3",
"fried-twinkie": "^0.2.2",
"polylint": "^2.10.4",
"typescript": "^2.x.x",

34
polygerrit-ui/app/.eslintrc.json
View File

@@ -88,13 +88,41 @@
"prefer-promise-reject-errors": "off",
"prefer-spread": "error",
"quote-props": ["error", "consistent-as-needed"],
"require-jsdoc": "off",
"semi": [2, "always"],
"template-curly-spacing": "error",
"valid-jsdoc": "off"
"require-jsdoc": 0,
"valid-jsdoc": 0,
"jsdoc/check-alignment": 2,
"jsdoc/check-examples": 0,
"jsdoc/check-indentation": 0,
"jsdoc/check-param-names": 0,
"jsdoc/check-syntax": 0,
"jsdoc/check-tag-names": 0,
"jsdoc/check-types": 0,
"jsdoc/implements-on-classes": 2,
"jsdoc/match-description": 0,
"jsdoc/newline-after-description": 2,
"jsdoc/no-types": 0,
"jsdoc/no-undefined-types": 0,
"jsdoc/require-description": 0,
"jsdoc/require-description-complete-sentence": 0,
"jsdoc/require-example": 0,
"jsdoc/require-hyphen-before-param-description": 0,
"jsdoc/require-jsdoc": 0,
"jsdoc/require-param": 0,
"jsdoc/require-param-description": 0,
"jsdoc/require-param-name": 2,
"jsdoc/require-param-type": 2,
"jsdoc/require-returns": 0,
"jsdoc/require-returns-check": 0,
"jsdoc/require-returns-description": 0,
"jsdoc/require-returns-type": 2,
"jsdoc/valid-types": 2
},
"plugins": [
"html"
"html",
"jsdoc"
],
"settings": {
"html/report-bad-indent": "error"

1
polygerrit-ui/app/behaviors/docs-url-behavior/docs-url-behavior.html
View File

@@ -31,6 +31,7 @@ limitations under the License.
/**
* Get the docs base URL from either the server config or by probing.
*
* @param {Object} config The server config.
* @param {!Object} restApi A REST API instance
* @return {!Promise<string>} A promise that resolves with the docs base

1
polygerrit-ui/app/behaviors/dom-util-behavior/dom-util-behavior.html
View File

@@ -25,6 +25,7 @@ limitations under the License.
/**
* Are any ancestors of the element (or the element itself) members of the
* given class.
*
* @param {!Element} element
* @param {string} className
* @param {Element=} opt_stopElement If provided, stop traversing the

2
polygerrit-ui/app/behaviors/gr-change-table-behavior/gr-change-table-behavior.html
View File

@@ -41,6 +41,7 @@ limitations under the License.
/**
* Returns the complement to the given column array
*
* @param {Array} columns
* @return {!Array}
*/
@@ -63,6 +64,7 @@ limitations under the License.
* The Project column was renamed to Repo, but some users may have
* preferences that use its old name. If that column is found, rename it
* before use.
*
* @param {!Array<string>} columns
* @return {!Array<string>} If the column was renamed, returns a new array
* with the corrected name. Otherwise, it returns the original param.

2
polygerrit-ui/app/behaviors/gr-patch-set-behavior/gr-patch-set-behavior.html
View File

@@ -52,6 +52,7 @@ limitations under the License.
/**
* Whether the given patch is a numbered parent of a merge (i.e. a negative
* number).
*
* @param {string|number} n
* @return {Boolean}
*/
@@ -264,6 +265,7 @@ limitations under the License.
/**
* Convert parent indexes from patch range expressions to numbers.
* For example, in a patch range expression `"-3"` becomes `3`.
*
* @param {number|string} rangeBase
* @return {number}
*/

2
polygerrit-ui/app/behaviors/gr-url-encoding-behavior/gr-url-encoding-behavior.html
View File

@@ -25,6 +25,7 @@ limitations under the License.
/**
* Pretty-encodes a URL. Double-encodes the string, and then replaces
* benevolent characters for legibility.
*
* @param {string} url
* @param {boolean=} replaceSlashes
* @return {string}
@@ -45,6 +46,7 @@ limitations under the License.
* Single decode for URL components. Will decode plus signs ('+') to spaces.
* Note: because this function decodes once, it is not the inverse of
* encodeURL.
*
* @param {string} url
* @return {string}
*/

2
polygerrit-ui/app/behaviors/safe-types-behavior/safe-types-behavior.html
View File

@@ -28,6 +28,7 @@ limitations under the License.
/**
* Wraps a string to be used as a URL. An error is thrown if the string cannot
* be considered safe.
*
* @constructor
* @param {string} url the unwrapped, potentially unsafe URL.
*/
@@ -40,6 +41,7 @@ limitations under the License.
/**
* Get the string representation of the safe URL.
*
* @returns {string}
*/
Gerrit.SafeTypes.SafeUrl.prototype.asString = function() {

1
polygerrit-ui/app/elements/admin/gr-access-section/gr-access-section.js
View File

@@ -25,6 +25,7 @@
/**
* Fired when a section that was previously added was removed.
*
* @event added-section-removed
*/

1
polygerrit-ui/app/elements/admin/gr-admin-group-list/gr-admin-group-list.js
View File

@@ -87,6 +87,7 @@
/**
* Opens the create overlay if the route has a hash 'create'
*
* @param {!Object} params
*/
_maybeOpenCreateOverlay(params) {

1
polygerrit-ui/app/elements/admin/gr-permission/gr-permission.js
View File

@@ -32,6 +32,7 @@
/**
* Fired when a permission that was previously added was removed.
*
* @event added-permission-removed
*/

1
polygerrit-ui/app/elements/admin/gr-repo-access/gr-repo-access.js
View File

@@ -345,6 +345,7 @@
/**
* As add / delete both can happen in the new section,
* so here to make sure it will remove the deleted ones.
*
* @see Issue 11339
*/
this._recursivelyRemoveDeleted(addRemoveObj.add[k]);

1
polygerrit-ui/app/elements/admin/gr-repo-list/gr-repo-list.js
View File

@@ -90,6 +90,7 @@
/**
* Opens the create overlay if the route has a hash 'create'
*
* @param {!Object} params
*/
_maybeOpenCreateOverlay(params) {

1
polygerrit-ui/app/elements/admin/gr-rule-editor/gr-rule-editor.js
View File

@@ -25,6 +25,7 @@
/**
* Fired when a rule that was previously added was removed.
*
* @event added-rule-removed
*/

1
polygerrit-ui/app/elements/change-list/gr-change-list-view/gr-change-list-view.js
View File

@@ -70,6 +70,7 @@
*
* Need sub-property declaration since it is used in template before
* assignment.
*
* @type {{ selectedChangeIndex: (number|undefined) }}
*
*/

1
polygerrit-ui/app/elements/change/gr-account-list/gr-account-list.js
View File

@@ -39,6 +39,7 @@
placeholder: String,
/**
* Needed for template checking since value is initially set to null.
*
* @type {?Object} */
pendingConfirmation: {
type: Object,

4
polygerrit-ui/app/elements/change/gr-change-actions/gr-change-actions.js
View File

@@ -203,7 +203,7 @@
/**
* Fired when an action is tapped.
*
* @event <action key>-tap
* @event custom-tap - naming pattern: <action key>-tap
*/
/**
@@ -800,6 +800,7 @@
/**
* Capitalize the first letter and lowecase all others.
*
* @param {string} s
* @return {string}
*/
@@ -1295,6 +1296,7 @@
/**
* Merge sources of change actions into a single ordered array of action
* values.
*
* @param {!Array} changeActionsRecord
* @param {!Array} revisionActionsRecord
* @param {!Array} primariesRecord

1
polygerrit-ui/app/elements/change/gr-change-metadata/gr-change-metadata.js
View File

@@ -410,6 +410,7 @@
/**
* Get the user with the specified role on the change. Returns null if the
* user with that role is the same as the owner.
*
* @param {!Object} change
* @param {string} role One of the values from _CHANGE_ROLE
* @return {Object|null} either an accound or null.

2
polygerrit-ui/app/elements/change/gr-change-view/gr-change-view.js
View File

@@ -810,6 +810,7 @@
/**
* Gets base patch number, if it is a parent try and decide from
* preference weather to default to `auto merge`, `Parent 1` or `PARENT`.
*
* @param {Object} change
* @param {Object} patchRange
* @return {number|string}
@@ -1282,6 +1283,7 @@
/**
* Reload the change.
*
* @param {boolean=} opt_reloadRelatedChanges Reloads the related chanegs
* when true.
* @return {Promise} A promise that resolves when the core data has loaded.

1
polygerrit-ui/app/elements/change/gr-file-list-header/gr-file-list-header.js
View File

@@ -160,6 +160,7 @@
/**
* Update the patchset description with the rest API.
*
* @param {string} desc
* @param {?(Event|Node)} e
* @return {!Promise}

15
polygerrit-ui/app/elements/change/gr-file-list/gr-file-list.js
View File

@@ -498,6 +498,7 @@
/**
* The closure compiler doesn't realize this.specialFilePathCompare is
* valid.
*
* @suppress {checkTypes}
*/
_normalizeChangeFilesResponse(response) {
@@ -906,6 +907,7 @@
/**
* Get a descriptive label for use in the status indicator's tooltip and
* ARIA label.
*
* @param {string} status
* @return {string}
*/
@@ -938,6 +940,7 @@
* entries in the expanded list, then render each diff corresponding in
* order by waiting for the previous diff to finish before starting the next
* one.
*
* @param {!Array} record The splice record in the expanded paths list.
*/
_expandedPathsChanged(record) {
@@ -982,6 +985,7 @@
* Given an array of paths and a NodeList of diff elements, render the diff
* for each path in order, awaiting the previous render to complete before
* continung.
*
* @param {!Array<string>} paths
* @param {!NodeList<!Object>} diffElements (GrDiffHostElement)
* @param {number} initialCount The total number of paths in the pass. This
@@ -1027,6 +1031,7 @@
/**
* In the given NodeList of diff elements, find the diff for the given path.
*
* @param {string} path
* @param {!NodeList<!Object>} diffElements (GrDiffElement)
* @return {!Object|undefined} (GrDiffElement)
@@ -1041,6 +1046,7 @@
/**
* Reset the comments of a modified thread
*
* @param {string} rootId
* @param {string} path
*/
@@ -1087,6 +1093,7 @@
* Update the loading class for the file list rows. The update is inside a
* debouncer so that the file list doesn't flash gray when the API requests
* are reasonably fast.
*
* @param {boolean} loading
*/
_loadingChanged(loading) {
@@ -1112,6 +1119,7 @@
/**
* Given a file path, return whether that path should have visible size bars
* and be included in the size bars calculation.
*
* @param {string} path
* @return {boolean}
*/
@@ -1121,6 +1129,7 @@
/**
* Compute size bar layout values from the file list.
*
* @return {Defs.LayoutStats|undefined}
*/
_computeSizeBarLayout(shownFilesRecord) {
@@ -1155,6 +1164,7 @@
/**
* Get the width of the addition bar for a file.
*
* @param {Object} file
* @param {Defs.LayoutStats} stats
* @return {number}
@@ -1172,6 +1182,7 @@
/**
* Get the x-offset of the addition bar for a file.
*
* @param {Object} file
* @param {Defs.LayoutStats} stats
* @return {number}
@@ -1183,6 +1194,7 @@
/**
* Get the width of the deletion bar for a file.
*
* @param {Object} file
* @param {Defs.LayoutStats} stats
* @return {number}
@@ -1200,6 +1212,7 @@
/**
* Get the x-offset of the deletion bar for a file.
*
* @param {Defs.LayoutStats} stats
* @return {number}
*/
@@ -1223,6 +1236,7 @@
/**
* Returns true if none of the inline diffs have been expanded.
*
* @return {boolean}
*/
_noDiffsExpanded() {
@@ -1233,6 +1247,7 @@
* Method to call via binding when each file list row is rendered. This
* allows approximate detection of when the dom-repeat has completed
* rendering.
*
* @param {number} index The index of the row being rendered.
* @return {string} an empty string.
*/

1
polygerrit-ui/app/elements/change/gr-messages-list/gr-messages-list.js
View File

@@ -206,6 +206,7 @@
* Computes message author's file comments for change's message.
* Method uses this.messages to find next message and relies on messages
* to be sorted by date field descending.
*
* @param {!Object} changeComments changeComment object, which includes
* a method to get all published comments (including robot comments),
* which returns a Hash of arrays of comments, filename as key.

3
polygerrit-ui/app/elements/change/gr-related-changes-list/gr-related-changes-list.js
View File

@@ -157,6 +157,7 @@
* Determines whether or not the given change has a parent change. If there
* is a relation chain, and the change id is not the last item of the
* relation chain, there is a parent.
*
* @param {number} currentChangeId
* @param {!Array} relatedChanges
* @return {boolean}
@@ -215,6 +216,7 @@
/**
* Do the given objects describe the same change? Compares the changes by
* their numbers.
*
* @see /Documentation/rest-api-changes.html#change-info
* @see /Documentation/rest-api-changes.html#related-change-and-commit-info
* @param {!Object} a Either ChangeInfo or RelatedChangeAndCommitInfo
@@ -232,6 +234,7 @@
* SubmittedTogetherInfo responses) or get the change number from a
* RelatedChangeAndCommitInfo (such as those included in a
* RelatedChangesInfo response).
*
* @see /Documentation/rest-api-changes.html#change-info
* @see /Documentation/rest-api-changes.html#related-change-and-commit-info
*

1
polygerrit-ui/app/elements/change/gr-reply-dialog/gr-reply-dialog.js
View File

@@ -677,6 +677,7 @@
* Generates a function to filter out reviewer/CC entries. When isCCs is
* truthy, the function filters out entries that already exist in this._ccs.
* When falsy, the function filters entries that exist in this._reviewers.
*
* @param {boolean} isCCs
* @return {!Function}
*/

2
polygerrit-ui/app/elements/change/gr-reviewer-list/gr-reviewer-list.js
View File

@@ -101,6 +101,7 @@
/**
* Returns hash of labels to max permitted score.
*
* @param {!Object} change
* @returns {!Object} labels to max permitted scores hash
*/
@@ -115,6 +116,7 @@
/**
* Returns max permitted score for reviewer.
*
* @param {!Object} reviewer
* @param {!Object} change
* @param {string} label

1
polygerrit-ui/app/elements/change/gr-thread-list/gr-thread-list.js
View File

@@ -62,6 +62,7 @@
* - Unresolved threads without drafts (reverse chronological)
* - Resolved threads with drafts (reverse chronological)
* - Resolved threads without drafts (reverse chronological)
*
* @param {!Object} changeRecord
*/
_computeSortedThreads(changeRecord) {

6
polygerrit-ui/app/elements/core/gr-navigation/gr-navigation.html
View File

@@ -217,6 +217,7 @@ limitations under the License.
/**
* Setup router implementation.
*
* @param {function(!string)} navigate the router-abstracted equivalent of
* `window.location.href = ...`. Takes a string.
* @param {function(!Object): string} generateUrl generates a URL given
@@ -253,6 +254,7 @@ limitations under the License.
/**
* Generate a URL for the given route parameters.
*
* @param {Object} params
* @return {string}
*/
@@ -329,6 +331,7 @@ limitations under the License.
/**
* Navigate to a search for changes with the given status.
*
* @param {string} status
*/
navigateToStatusSearch(status) {
@@ -340,6 +343,7 @@ limitations under the License.
/**
* Navigate to a search query
*
* @param {string} query
* @param {number=} opt_offset
*/
@@ -538,6 +542,7 @@ limitations under the License.
/**
* Navigate to an arbitrary relative URL.
*
* @param {string} relativeUrl
*/
navigateToRelativeUrl(relativeUrl) {
@@ -560,6 +565,7 @@ limitations under the License.
/**
* Navigate to a repo settings page.
*
* @param {string} repoName
*/
navigateToRepo(repoName) {

6
polygerrit-ui/app/elements/core/gr-reporting/gr-reporting.js
View File

@@ -175,6 +175,7 @@
/**
* The default reporter reports events immediately.
*
* @param {string} type
* @param {string} category
* @param {string} eventName
@@ -202,6 +203,7 @@
/**
* The caching reporter will queue reports until plugins have loaded, and
* log events immediately if they're reported after plugins have loaded.
*
* @param {string} type
* @param {string} category
* @param {string} eventName
@@ -345,6 +347,7 @@
/**
* Reports just line timeEnd, but additionally reports an average given a
* denominator and a separate reporiting name for the average.
*
* @param {string} name Timing name.
* @param {string} averageName Average timing name.
* @param {number} denominator Number by which to divide the total to
@@ -363,6 +366,7 @@
/**
* Send a timing report with an arbitrary time value.
*
* @param {string} name Timing name.
* @param {number} time The time to report as an integer of milliseconds.
*/
@@ -375,6 +379,7 @@
* Get a timer object to for reporing a user timing. The start time will be
* the time that the object has been created, and the end time will be the
* time that the "end" method is called on the object.
*
* @param {string} name Timing name.
* @returns {!Object} The timer object.
*/
@@ -421,6 +426,7 @@
/**
* Log timing information for an RPC.
*
* @param {string} anonymizedUrl The URL of the RPC with tokens obfuscated.
* @param {number} elapsed The time elapsed of the RPC.
*/

6
polygerrit-ui/app/elements/core/gr-router/gr-router.js
View File

@@ -103,6 +103,7 @@
/**
* Support vestigial params from GWT UI.
*
* @see Issue 7673.
* @type {!RegExp}
*/
@@ -159,6 +160,7 @@
* the hash of diff URLs. In this format, a number on its own indicates that
* line number in the revision of the diff. A number prefixed by either an 'a'
* or a 'b' indicates that line number of the base of the diff.
*
* @type {RegExp}
*/
const LINE_ADDRESS_PATTERN = /^([ab]?)(\d+)$/;
@@ -521,6 +523,7 @@
* Given an object of parameters, potentially including a `patchNum` or a
* `basePatchNum` or both, return a string representation of that range. If
* no range is indicated in the params, the empty string is returned.
*
* @param {!Object} params
* @return {string}
*/
@@ -597,6 +600,7 @@
/**
* Redirect the user to login using the given return-URL for redirection
* after authentication success.
*
* @param {string} returnUrl
*/
_redirectToLogin(returnUrl) {
@@ -609,6 +613,7 @@
* Hashes parsed by page.js exclude "inner" hashes, so a URL like "/a#b#c"
* is parsed to have a hash of "b" rather than "b#c". Instead, this method
* parses hashes correctly. Will return an empty string if there is no hash.
*
* @param {!string} canonicalPath
* @return {!string} Everything after the first '#' ("a#b#c" -> "b#c").
*/
@@ -629,6 +634,7 @@
* Check to see if the user is logged in and return a promise that only
* resolves if the user is logged in. If the user us not logged in, the
* promise is rejected and the page is redirected to the login flow.
*
* @param {!Object} data The parsed route data.
* @return {!Promise<!Object>} A promise yielding the original route data
* (if it resolves).

2
polygerrit-ui/app/elements/core/gr-search-bar/gr-search-bar.js
View File

@@ -204,6 +204,7 @@
/**
* Determine what array of possible suggestions should be provided
* to _getSearchSuggestions.
*
* @param {string} input - The full search term, in lowercase.
* @return {!Promise} This returns a promise that resolves to an array of
* suggestion objects.
@@ -245,6 +246,7 @@
/**
* Get the sorted, pruned list of suggestions for the current search query.
*
* @param {string} input - The complete search query.
* @return {!Promise} This returns a promise that resolves to an array of
* suggestions.

3
polygerrit-ui/app/elements/core/gr-smart-search/gr-smart-search.js
View File

@@ -70,6 +70,7 @@
/**
* Fetch from the API the predicted projects.
*
* @param {string} predicate - The first part of the search term, e.g.
* 'project'
* @param {string} expression - The second part of the search term, e.g.
@@ -90,6 +91,7 @@
/**
* Fetch from the API the predicted groups.
*
* @param {string} predicate - The first part of the search term, e.g.
* 'ownerin'
* @param {string} expression - The second part of the search term, e.g.
@@ -111,6 +113,7 @@
/**
* Fetch from the API the predicted accounts.
*
* @param {string} predicate - The first part of the search term, e.g.
* 'owner'
* @param {string} expression - The second part of the search term, e.g.

3
polygerrit-ui/app/elements/diff/gr-comment-api/gr-comment-api.js
View File

@@ -428,6 +428,7 @@
/**
* Whether the given comment should be included in the base side of the
* given patch range.
*
* @param {!Object} comment
* @param {!Defs.patchRange} range
* @return {boolean}
@@ -459,6 +460,7 @@
/**
* Whether the given comment should be included in the revision side of the
* given patch range.
*
* @param {!Object} comment
* @param {!Defs.patchRange} range
* @return {boolean}
@@ -471,6 +473,7 @@
/**
* Whether the given comment should be included in the given patch range.
*
* @param {!Object} comment
* @param {!Defs.patchRange} range
* @return {boolean|undefined}

2
polygerrit-ui/app/elements/diff/gr-diff-builder/gr-diff-builder.html
View File

@@ -452,6 +452,7 @@ limitations under the License.
* which, in turn, triggers a reflow on the page. Create a hidden
* thread, attach it to the page, and remove it so the stylesheet will
* already exist and the user's comment will be quick to load.
*
* @see https://gerrit-review.googlesource.com/c/82213/
*/
_preRenderThread() {
@@ -489,6 +490,7 @@ limitations under the License.
/**
* Get the approximate length of the diff as the sum of the maximum
* length of the chunks.
*
* @return {number}
*/
getDiffLength() {

9
polygerrit-ui/app/elements/diff/gr-diff-builder/gr-diff-builder.js
View File

@@ -95,6 +95,7 @@
/**
* Abstract method
*
* @param {string} outputEl
* @param {number} fontSize
*/
@@ -104,6 +105,7 @@
/**
* Abstract method
*
* @param {Object} group
*/
GrDiffBuilder.prototype.buildSectionElement = function() {
@@ -623,6 +625,7 @@
/**
* Finds the next DIV.contentText element following the given element, and on
* the same side. Will only search within a group.
*
* @param {HTMLElement} content
* @param {string} side Either 'left' or 'right'
* @return {HTMLElement}
@@ -634,6 +637,7 @@
/**
* Determines whether the given group is either totally an addition or totally
* a removal.
*
* @param {!Object} group (GrDiffGroup)
* @return {boolean}
*/
@@ -646,6 +650,7 @@
/**
* Set the blame information for the diff. For any already-rendered line,
* re-render its blame cell content.
*
* @param {Object} blame
*/
GrDiffBuilder.prototype.setBlame = function(blame) {
@@ -673,6 +678,7 @@
/**
* Find the blame cell for a given line number.
*
* @param {number} lineNum
* @return {HTMLTableDataCellElement}
*/
@@ -685,6 +691,7 @@
* Given a base line number, return the commit containing that line in the
* current set of blame information. If no blame information has been
* provided, null is returned.
*
* @param {number} lineNum
* @return {Object} The commit information.
*/
@@ -704,6 +711,7 @@
/**
* Given the number of a base line, get the content for the blame cell of that
* line. If there is no blame information for that line, returns null.
*
* @param {number} lineNum
* @param {Object=} opt_commit Optionally provide the commit object, so that
* it does not need to be searched.
@@ -728,6 +736,7 @@
/**
* Create a blame cell for the given base line. Blame information will be
* included in the cell if available.
*
* @param {GrDiffLine} line
* @return {HTMLTableDataCellElement}
*/

1
polygerrit-ui/app/elements/diff/gr-diff-comment-thread/gr-diff-comment-thread.js
View File

@@ -453,6 +453,7 @@
/**
* Load the project config when a project name has been provided.
*
* @param {string} name The project name.
*/
_projectNameChanged(name) {

5
polygerrit-ui/app/elements/diff/gr-diff-cursor/gr-diff-cursor.js
View File

@@ -66,7 +66,7 @@
* the first chunk) the next time the diff renders. It is set back to null
* when used.
*
* @type (?number)
* @type {?number}
*/
initialLineNumber: {
type: Number,
@@ -173,6 +173,7 @@
/**
* Get the line number element targeted by the cursor row and side.
*
* @return {?Element|undefined}
*/
getTargetLineElement() {
@@ -240,6 +241,7 @@
* {leftSide: false, number: 123} for line 123 of the revision, or
* {leftSide: true, number: 321} for line 321 of the base patch.
* Returns null if an address is not available.
*
* @return {?Object}
*/
getAddress() {
@@ -364,6 +366,7 @@
/**
* Setup and tear down on-render listeners for any diffs that are added or
* removed from the cursor.
*
* @private
*/
_diffsChanged(changeRecord) {

1
polygerrit-ui/app/elements/diff/gr-diff-highlight/gr-annotation.js
View File

@@ -31,6 +31,7 @@
/**
* The DOM API textContent.length calculation is broken when the text
* contains Unicode. See https://mathiasbynens.be/notes/javascript-unicode .
*
* @param {!Text} node text node.
* @return {number} The length of the text.
*/

2
polygerrit-ui/app/elements/diff/gr-diff-highlight/gr-diff-highlight.js
View File

@@ -107,6 +107,7 @@
* Merges multiple ranges, accounts for triple click, accounts for
* syntax highligh, convert native DOM Range objects to Gerrit concepts
* (line, side, etc).
*
* @return {({
* start: {
* node: Node,
@@ -142,6 +143,7 @@
/**
* Normalize a specific DOM Range.
*
* @return {!Object} fixed normalized range
*/
_normalizeRange(domRange) {

1
polygerrit-ui/app/elements/diff/gr-diff-highlight/gr-range-normalizer.js
View File

@@ -97,6 +97,7 @@
/**
* The DOM API textContent.length calculation is broken when the text
* contains Unicode. See https://mathiasbynens.be/notes/javascript-unicode .
*
* @param {text} node A text node.
* @return {number} The length of the text.
*/

4
polygerrit-ui/app/elements/diff/gr-diff-host/gr-diff-host.js
View File

@@ -57,6 +57,7 @@
/**
* Fired when the user selects a line.
*
* @event line-selected
*/
@@ -123,6 +124,7 @@
/**
* Special line number which should not be collapsed into a shared region.
*
* @type {{
* number: number,
* leftSide: {boolean}
@@ -284,6 +286,7 @@
/**
* Load and display blame information for the base of the diff.
*
* @return {Promise} A promise that resolves when blame finishes rendering.
*/
loadBlame() {
@@ -458,6 +461,7 @@
* Take a diff that was loaded with a ignore-whitespace other than
* IGNORE_NONE, and convert delta chunks labeled as common into shared
* chunks.
*
* @param {!Object} diff
* @returns {!Object}
*/

6
polygerrit-ui/app/elements/diff/gr-diff-processor/gr-diff-processor.js
View File

@@ -104,6 +104,7 @@
/**
* Asynchronously process the diff object into groups. As it processes, it
* will splice groups into the `groups` property of the component.
*
* @return {Promise} A promise that resolves when the diff is completely
* processed.
*/
@@ -230,6 +231,7 @@
/**
* Take rows of a shared diff section and produce an array of corresponding
* (potentially collapsed) groups.
*
* @param {!Array<string>} rows
* @param {number} context
* @param {number} startLineNumLeft
@@ -293,6 +295,7 @@
/**
* Take the rows of a delta diff section and produce the corresponding
* group.
*
* @param {!Array<string>} rowsAdded
* @param {!Array<string>} rowsRemoved
* @param {number} startLineNumLeft
@@ -353,6 +356,7 @@
* In order to show comments out of the bounds of the selected context,
* treat them as separate chunks within the model so that the content (and
* context surrounding it) renders correctly.
*
* @param {?} content The diff content object. (has to be iterable)
* @return {!Object} A new diff content object with regions split up.
*/
@@ -497,6 +501,7 @@
* If a group is an addition or a removal, break it down into smaller groups
* of that type using the MAX_GROUP_SIZE. If the group is a shared section
* or a delta it is returned as the single element of the result array.
*
* @param {!Object} group A raw chunk from a diff response.
* @return {!Array<!Array<!Object>>}
*/
@@ -526,6 +531,7 @@
/**
* Given an array and a size, return an array of arrays where no inner array
* is larger than that size, preserving the original order.
*
* @param {!Array<T>} array
* @param {number} size
* @return {!Array<!Array<T>>}

1
polygerrit-ui/app/elements/diff/gr-diff-selection/gr-diff-selection.js
View File

@@ -101,6 +101,7 @@
/**
* Set the provided list of classes on the element, to the exclusion of all
* other SelectionClass values.
*
* @param {!Array<!string>} targetClasses
*/
_setClasses(targetClasses) {

6
polygerrit-ui/app/elements/diff/gr-diff/gr-diff.js
View File

@@ -54,6 +54,7 @@
/**
* Fired when the user selects a line.
*
* @event line-selected
*/
@@ -126,6 +127,7 @@
/**
* Special line number which should not be collapsed into a shared region.
*
* @type {{
* number: number,
* leftSide: {boolean}
@@ -167,7 +169,7 @@
* bypassed. If the value is a number, then that number represents the
* context preference to use when rendering the bypassed diff.
*
* @type (number|null)
* @type {number|null}
*/
_safetyBypass: {
type: Number,
@@ -746,6 +748,7 @@
/**
* Find the last chunk for the given side.
*
* @param {!Object} diff
* @param {boolean} leftSide true if checking the base of the diff,
* false if testing the revision.
@@ -781,6 +784,7 @@
/**
* Check whether the specified side of the diff has a trailing newline.
*
* @param {!Object} diff
* @param {boolean} leftSide true if checking the base of the diff,
* false if testing the revision.

1
polygerrit-ui/app/elements/diff/gr-patch-range-select/gr-patch-range-select.js
View File

@@ -157,6 +157,7 @@
* The basePatchNum should always be <= patchNum -- because sortedRevisions
* is sorted in reverse order (higher patchset nums first), invalid base
* patch nums have an index greater than the index of patchNum.
*
* @param {number|string} basePatchNum The possible base patch num.
* @param {number|string} patchNum The current selected patch num.
* @param {!Array} sortedRevisions

5
polygerrit-ui/app/elements/diff/gr-ranged-comment-layer/gr-ranged-comment-layer.js
View File

@@ -46,6 +46,7 @@
/**
* Layer method to add annotations to a line.
*
* @param {!HTMLElement} el The DIV.contentText element to apply the
* annotation to.
* @param {!Object} line The line object. (GrDiffLine)
@@ -72,6 +73,7 @@
/**
* Register a listener for layer updates.
*
* @param {function(number, number, string)} fn The update handler function.
* Should accept as arguments the line numbers for the start and end of
* the update and the side as a string.
@@ -82,6 +84,7 @@
/**
* Notify Layer listeners of changes to annotations.
*
* @param {number} start The line where the update starts.
* @param {number} end The line where the update ends.
* @param {string} side The side of the update. ('left' or 'right')
@@ -95,6 +98,7 @@
/**
* Handle change in the comments by updating the comment maps and by
* emitting appropriate update notifications.
*
* @param {Object} record The change record.
*/
_handleCommentChange(record) {
@@ -136,6 +140,7 @@
* Take a list of comments and return a sparse list mapping line numbers to
* partial ranges. Uses an end-character-index of -1 to indicate the end of
* the line.
*
* @param {?} commentList The list of comments.
* Getting this param to match closure requirements caused problems.
* @return {!Object} The sparse list.

6
polygerrit-ui/app/elements/diff/gr-syntax-layer/gr-syntax-layer.js
View File

@@ -168,6 +168,7 @@
/**
* Annotation layer method to add syntax annotations to the given element
* for the given line.
*
* @param {!HTMLElement} el
* @param {!Object} line (GrDiffLine)
*/
@@ -204,6 +205,7 @@
/**
* Start processing symtax for the loaded diff and notify layer listeners
* as syntax info comes online.
*
* @return {Promise}
*/
process() {
@@ -291,6 +293,7 @@
* Take a string of HTML with the (potentially nested) syntax markers
* Highlight.js emits and emit a list of text ranges and classes for the
* markers.
*
* @param {string} str The string of HTML.
* @return {!Array<!Object>} The list of ranges.
*/
@@ -326,6 +329,7 @@
/**
* For a given state, process the syntax for the next line (or pair of
* lines).
*
* @param {!Object} state The processing state for the layer.
*/
_processNextLine(state) {
@@ -438,6 +442,7 @@
/**
* Tells whether the state has exhausted its current section.
*
* @param {!Object} state
* @return {boolean}
*/
@@ -454,6 +459,7 @@
/**
* For a given state, notify layer listeners of any processed line ranges
* that have not yet been notified.
*
* @param {!Object} state
*/
_notify(state) {

2
polygerrit-ui/app/elements/edit/gr-edit-controls/gr-edit-controls.js
View File

@@ -111,6 +111,7 @@
/**
* Given a path string, checks that it is a valid file path.
*
* @param {string} path
* @return {boolean}
*/
@@ -125,6 +126,7 @@
/**
* Given a dom event, gets the dialog that lies along this event path.
*
* @param {!Event} e
* @return {!Element|undefined}
*/

1
polygerrit-ui/app/elements/gr-app.js
View File

@@ -51,6 +51,7 @@
/**
* The last time the g key was pressed in milliseconds (or a keydown event
* was handled if the key is held down).
*
* @type {number|null}
*/
_lastGKeyPressTimestamp: {

1
polygerrit-ui/app/elements/plugins/gr-attribute-helper/gr-attribute-helper.js
View File

@@ -28,6 +28,7 @@
/**
* Returns true if the property is defined on wrapped element.
*
* @param {string} name
* @return {boolean}
*/

2
polygerrit-ui/app/elements/plugins/gr-dom-hooks/gr-dom-hooks.js
View File

@@ -76,6 +76,7 @@
/**
* Get instance of last DOM hook element attached into the endpoint.
* Returns a Promise, that's resolved when attachment is done.
*
* @return {!Promise<!Element>}
*/
GrDomHook.prototype.getLastAttached = function() {
@@ -108,6 +109,7 @@
/**
* Install a new callback to invoke when a new instance of DOM hook element
* is attached.
*
* @param {function(Element)} callback
*/
GrDomHook.prototype.onAttached = function(callback) {

1
polygerrit-ui/app/elements/plugins/gr-endpoint-decorator/gr-endpoint-decorator.js
View File

@@ -33,6 +33,7 @@
* This map prevents importing the same endpoint twice.
* Without caching, if a plugin is loaded after the loaded plugins
* callback fires, it will be imported twice and appear twice on the page.
*
* @type {!Map}
*/
_initializedPlugins: {

3
polygerrit-ui/app/elements/plugins/gr-event-helper/gr-event-helper.js
View File

@@ -25,6 +25,7 @@
/**
* Add a callback to arbitrary event.
* The callback may return false to prevent event bubbling.
*
* @param {string} event Event name
* @param {function(Event):boolean} callback
* @return {function()} Unsubscribe function.
@@ -36,6 +37,7 @@
/**
* Add a callback to element click or touch.
* The callback may return false to prevent event bubbling.
*
* @param {function(Event):boolean} callback
* @return {function()} Unsubscribe function.
*/
@@ -48,6 +50,7 @@
* Callback is installed on parent during capture phase.
* https://www.w3.org/TR/DOM-Level-3-Events/#event-flow
* The callback may return false to cancel regular event listeners.
*
* @param {function(Event):boolean} callback
* @return {function()} Unsubscribe function.
*/

2
polygerrit-ui/app/elements/plugins/gr-popup-interface/gr-popup-interface.js
View File

@@ -22,6 +22,7 @@
* Provides method for opening and closing popups from plugin.
* opt_moduleName is a name of custom element that will be automatically
* inserted on popup opening.
*
* @param {!Object} plugin
* @param {opt_moduleName=} string
*/
@@ -40,6 +41,7 @@
* Opens the popup, inserts it into DOM over current UI.
* Creates the popup if not previously created. Creates popup content element,
* if it was provided with constructor.
*
* @returns {!Promise<!Object>}
*/
GrPopupInterface.prototype.open = function() {

1
polygerrit-ui/app/elements/settings/gr-change-table-editor/gr-change-table-editor.js
View File

@@ -38,6 +38,7 @@
/**
* Get the list of enabled column names from whichever checkboxes are
* checked (excluding the number checkbox).
*
* @return {!Array<string>}
*/
_getDisplayedColumns() {

1
polygerrit-ui/app/elements/shared/gr-autocomplete/gr-autocomplete.js
View File

@@ -215,6 +215,7 @@
/**
* Set the text of the input without triggering the suggestion dropdown.
*
* @param {string} text The new text for the input.
*/
setText(text) {

12
polygerrit-ui/app/elements/shared/gr-cursor-manager/gr-cursor-manager.js
View File

@@ -34,7 +34,7 @@
observer: '_updateIndex',
},
/**
* @type (?Object)
* @type {?Object}
*/
target: {
type: Object,
@@ -43,7 +43,8 @@
},
/**
* The height of content intended to be included with the target.
* @type (?number)
*
* @type {?number}
*/
_targetHeight: Number,
@@ -69,7 +70,8 @@
* 'keep-visible'. 'keep-visible' will only scroll if the cursor is beyond
* the viewport.
* TODO (beckysiegel) figure out why it can be undefined
* @type (string|undefined)
*
* @type {string|undefined}
*/
scrollBehavior: {
type: String,
@@ -99,6 +101,7 @@
/**
* Set the cursor to an arbitrary element.
*
* @param {!HTMLElement} element
* @param {boolean=} opt_noScroll prevent any potential scrolling in response
* setting the cursor.
@@ -146,6 +149,7 @@
/**
* Move the cursor forward or backward by delta. Noop if moving past either
* end of the stop list.
*
* @param {number} delta either -1 or 1.
* @param {!Function=} opt_condition Optional stop condition. If a condition
* is passed the cursor will continue to move in the specified direction
@@ -200,6 +204,7 @@
/**
* Get the next stop index indicated by the delta direction.
*
* @param {number} delta either -1 or 1.
* @param {!Function=} opt_condition Optional stop condition.
* @return {number} the new index.
@@ -248,6 +253,7 @@
/**
* Calculate where the element is relative to the window.
*
* @param {!Object} target Target to scroll to.
* @return {number} Distance to top of the target.
*/

2
polygerrit-ui/app/elements/shared/gr-dropdown-list/gr-dropdown-list.js
View File

@@ -73,6 +73,7 @@
/**
* Handle a click on the iron-dropdown element.
*
* @param {!Event} e
*/
_handleDropdownClick(e) {
@@ -85,6 +86,7 @@
/**
* Handle a click on the button to open the dropdown.
*
* @param {!Event} e
*/
_showDropdownTapHandler(e) {

13
polygerrit-ui/app/elements/shared/gr-dropdown/gr-dropdown.js
View File

@@ -92,6 +92,7 @@
/**
* Handle the up key.
*
* @param {!Event} e
*/
_handleUp(e) {
@@ -106,6 +107,7 @@
/**
* Handle the down key.
*
* @param {!Event} e
*/
_handleDown(e) {
@@ -120,6 +122,7 @@
/**
* Handle the tab key.
*
* @param {!Event} e
*/
_handleTab(e) {
@@ -132,6 +135,7 @@
/**
* Handle the enter key.
*
* @param {!Event} e
*/
_handleEnter(e) {
@@ -150,6 +154,7 @@
/**
* Handle a click on the iron-dropdown element.
*
* @param {!Event} e
*/
_handleDropdownClick(e) {
@@ -158,6 +163,7 @@
/**
* Hanlde a click on the button to open the dropdown.
*
* @param {!Event} e
*/
_dropdownTriggerTapHandler(e) {
@@ -190,6 +196,7 @@
/**
* Get the class for a top-content item based on the given boolean.
*
* @param {boolean} bold Whether the item is bold.
* @return {string} The class for the top-content item.
*/
@@ -200,6 +207,7 @@
/**
* Build a URL for the given host and path. The base URL will be only added,
* if it is not already included in the path.
*
* @param {!string} host
* @param {!string} path
* @return {!string} The scheme-relative URL.
@@ -214,6 +222,7 @@
* Build a scheme-relative URL for the current host. Will include the base
* URL if one is present. Note: the URL will be scheme-relative but absolute
* with regard to the host.
*
* @param {!string} path The path for the URL.
* @return {!string} The scheme-relative URL.
*/
@@ -224,6 +233,7 @@
/**
* Compute the URL for a link object.
*
* @param {!Object} link The object describing the link.
* @return {!string} The URL.
*/
@@ -241,6 +251,7 @@
* Compute the value for the rel attribute of an anchor for the given link
* object. If the link has a target value, then the rel must be "noopener"
* for security reasons.
*
* @param {!Object} link The object describing the link.
* @return {?string} The rel value for the link.
*/
@@ -253,6 +264,7 @@
/**
* Handle a click on an item of the dropdown.
*
* @param {!Event} e
*/
_handleItemTap(e) {
@@ -268,6 +280,7 @@
/**
* If a dropdown item is shown as a button, get the class for the button.
*
* @param {string} id
* @param {!Object} disabledIdsRecord The change record for the disabled IDs
* list.

1
polygerrit-ui/app/elements/shared/gr-event-interface/gr-event-interface.js
View File

@@ -39,6 +39,7 @@
constructor() {
/**
* Shared events map from name to the listeners.
*
* @type {!Object<string, Array<eventCallback>>}
*/
this._listenersMap = new Map();

1
polygerrit-ui/app/elements/shared/gr-formatted-text/gr-formatted-text.js
View File

@@ -245,6 +245,7 @@
/**
* Map an array of block objects to an array of DOM nodes.
*
* @param {!Array<!Object>} blocks
* @return {!Array<!HTMLElement>}
*/

2
polygerrit-ui/app/elements/shared/gr-js-api-interface/gr-annotation-actions-context.js
View File

@@ -19,6 +19,7 @@
/**
* Used to create a context for GrAnnotationActionsInterface.
*
* @param {HTMLElement} el The DIV.contentText element to apply the
* annotation to using annotateRange.
* @param {GrDiffLine} line The line object.
@@ -37,6 +38,7 @@
/**
* Method to add annotations to a line.
*
* @param {Number} start The line number where the update starts.
* @param {Number} end The line number where the update ends.
* @param {String} cssClass The name of a CSS class created using Gerrit.css.

8
polygerrit-ui/app/elements/shared/gr-js-api-interface/gr-annotation-actions-js-api.js
View File

@@ -34,6 +34,7 @@
* Register a function to call to apply annotations. Plugins should use
* GrAnnotationActionsContext.annotateRange to apply a CSS class to a range
* within a line.
*
* @param {function(GrAnnotationActionsContext)} addLayerFunc The function
* that will be called when the AnnotationLayer is ready to annotate.
*/
@@ -45,6 +46,7 @@
/**
* The specified function will be called with a notify function for the plugin
* to call when it has all required data for annotation. Optional.
*
* @param {function(function(String, Number, Number, String))} notifyFunc See
* doc of the notify function below to see what it does.
*/
@@ -97,6 +99,7 @@
* The notify function will call the listeners of all required annotation
* layers. Intended to be called by the plugin when all required data for
* annotation is available.
*
* @param {String} path The file path whose listeners should be notified.
* @param {Number} start The line where the update starts.
* @param {Number} end The line where the update ends.
@@ -117,6 +120,7 @@
/**
* Should be called to register annotation layers by the framework. Not
* intended to be called by plugins.
*
* @param {String} path The file path (eg: /COMMIT_MSG').
* @param {String} changeNum The Gerrit change number.
* @param {String} patchNum The Gerrit patch number.
@@ -131,6 +135,7 @@
/**
* Used to create an instance of the Annotation Layer interface.
*
* @param {String} path The file path (eg: /COMMIT_MSG').
* @param {String} changeNum The Gerrit change number.
* @param {String} patchNum The Gerrit patch number.
@@ -148,6 +153,7 @@
/**
* Register a listener for layer updates.
*
* @param {function(Number, Number, String)} fn The update handler function.
* Should accept as arguments the line numbers for the start and end of
* the update and the side as a string.
@@ -158,6 +164,7 @@
/**
* Layer method to add annotations to a line.
*
* @param {HTMLElement} el The DIV.contentText element to apply the
* annotation to.
* @param {GrDiffLine} line The line object.
@@ -170,6 +177,7 @@
/**
* Notify Layer listeners of changes to annotations.
*
* @param {Number} start The line where the update starts.
* @param {Number} end The line where the update ends.
* @param {String} side The side of the update. ('left' or 'right')

2
polygerrit-ui/app/elements/shared/gr-js-api-interface/gr-change-actions-js-api.js
View File

@@ -20,6 +20,7 @@
/**
* Ensure GrChangeActionsInterface instance has access to gr-change-actions
* element and retrieve if the interface was created before element.
*
* @param {!GrChangeActionsInterface} api
*/
function ensureEl(api) {
@@ -32,6 +33,7 @@
/**
* Set gr-change-actions element to a GrChangeActionsInterface instance.
*
* @param {!GrChangeActionsInterface} api
* @param {!Element} el gr-change-actions
*/

1
polygerrit-ui/app/elements/shared/gr-js-api-interface/gr-change-reply-js-api.js
View File

@@ -20,6 +20,7 @@
/**
* Ensure GrChangeReplyInterface instance has access to gr-reply-dialog
* element and retrieve if the interface was created before element.
*
* @param {!GrChangeReplyInterfaceOld} api
*/
function ensureEl(api) {

3
polygerrit-ui/app/elements/shared/gr-js-api-interface/gr-plugin-endpoints.js
View File

@@ -66,6 +66,7 @@
/**
* Get detailed information about modules registered with an extension
* endpoint.
*
* @param {string} name Endpoint name.
* @param {?{
* type: (string|undefined),
@@ -92,6 +93,7 @@
/**
* Get detailed module names for instantiating at the endpoint.
*
* @param {string} name Endpoint name.
* @param {?{
* type: (string|undefined),
@@ -109,6 +111,7 @@
/**
* Get .html plugin URLs with element and module definitions.
*
* @param {string} name Endpoint name.
* @param {?{
* type: (string|undefined),

2
polygerrit-ui/app/elements/shared/gr-js-api-interface/gr-plugin-rest-api.js
View File

@@ -48,6 +48,7 @@
/**
* Fetch and return native browser REST API Response.
*
* @param {string} method HTTP Method (GET, POST, etc)
* @param {string} url URL without base path or plugin prefix
* @param {Object=} payload Respected for POST and PUT only.
@@ -63,6 +64,7 @@
/**
* Fetch and parse REST API response, if request succeeds.
*
* @param {string} method HTTP Method (GET, POST, etc)
* @param {string} url URL without base path or plugin prefix
* @param {Object=} payload Respected for POST and PUT only.

2
polygerrit-ui/app/elements/shared/gr-js-api-interface/gr-public-js-api.js
View File

@@ -294,6 +294,7 @@
/**
* To make REST requests for plugin-provided endpoints, use
*
* @example
* const pluginRestApi = plugin.restApi(plugin.url());
*
@@ -567,6 +568,7 @@
/**
* Install "stepping stones" API for GWT-compiled plugins by default.
*
* @deprecated best effort support, will be removed with GWT UI.
*/
Gerrit.installGwt = function(url) {

5
polygerrit-ui/app/elements/shared/gr-lib-loader/gr-lib-loader.js
View File

@@ -40,6 +40,7 @@
* Get the HLJS library. Returns a promise that resolves with a reference to
* the library after it's been loaded. The promise resolves immediately if
* it's already been loaded.
*
* @return {!Promise<Object>}
*/
getHLJS() {
@@ -64,6 +65,7 @@
/**
* Loads the dark theme document. Returns a promise that resolves with a
* custom-style DOM element.
*
* @return {!Promise<Element>}
*/
getDarkTheme() {
@@ -91,6 +93,7 @@
/**
* Get the HLJS library, assuming it has been loaded. Configure the library
* if it hasn't already been configured.
*
* @return {!Object}
*/
_getHighlightLib() {
@@ -106,6 +109,7 @@
/**
* Get the resource path used to load the application. If the application
* was loaded through a CDN, then this will be the path to CDN resources.
*
* @return {string}
*/
_getLibRoot() {
@@ -117,6 +121,7 @@
/**
* Load and execute a JS file from the lib root.
*
* @param {string} src The path to the JS file without the lib root.
* @return {Promise} a promise that resolves when the script's onload
* executes.

2
polygerrit-ui/app/elements/shared/gr-linked-text/gr-linked-text.js
View File

@@ -54,6 +54,7 @@
/**
* Because either the source text or the linkification config has changed,
* the content should be re-parsed.
*
* @param {string|null|undefined} content The raw, un-linkified source
* string to parse.
* @param {Object|null|undefined} config The server config specifying
@@ -83,6 +84,7 @@
* element should be created and attached to the resulting DOM.
* - To attach an arbitrary fragment: when called with only the `fragment`
* argument, the fragment should be attached to the resulting DOM as is.
*
* @param {string|null} text
* @param {string|null} href
* @param {DocumentFragment|undefined} fragment

12
polygerrit-ui/app/elements/shared/gr-linked-text/link-text-parser.js
View File

@@ -30,6 +30,7 @@
/**
* Pattern describing URLs with supported protocols.
*
* @type {RegExp}
*/
const URL_PROTOCOL_PATTERN = /^(https?:\/\/|mailto:)/;
@@ -38,6 +39,7 @@
* Construct a parser for linkifying text. Will linkify plain URLs that appear
* in the text as well as custom links if any are specified in the linkConfig
* parameter.
*
* @param {Object|null|undefined} linkConfig Comment links as specified by the
* commentlinks field on a project config.
* @param {Function} callback The callback to be fired when an intermediate
@@ -56,6 +58,7 @@
/**
* Emit a callback to create a link element.
*
* @param {string} text The text of the link.
* @param {string} href The URL to use as the href of the link.
*/
@@ -67,6 +70,7 @@
/**
* Given the source text and a list of CommentLinkItem objects that were
* generated by the commentlinks config, emit parsing callbacks.
*
* @param {string} text The chuml of source text over which the outputArray
* items range.
* @param {!Array<Defs.CommentLinkItem>} outputArray The list of items to add
@@ -104,6 +108,7 @@
/**
* Sort the given array of CommentLinkItems such that the positions are in
* reverse order.
*
* @param {!Array<Defs.CommentLinkItem>} outputArray
*/
GrLinkTextParser.prototype.sortArrayReverse = function(outputArray) {
@@ -119,6 +124,7 @@
* - With the `html` paremeter provided, and the `text` and `href` parameters
* passed as `null`. In this case, the string of HTML will be parsed and the
* first resulting node will be used as the resulting content.
*
* @param {string|null} text The text to use if creating a link.
* @param {string|null} href The href to use as the URL if creating a link.
* @param {string|null} html The html to parse and use as the result.
@@ -161,6 +167,7 @@
/**
* Create a CommentLinkItem for a link and append it to the given output
* array.
*
* @param {string|null} text The text for the link.
* @param {string|null} href The href to use as the URL of the link.
* @param {number} position The position inside the source text where the link
@@ -183,6 +190,7 @@
/**
* Create a CommentLinkItem specified by an HTMl string and append it to the
* given output array.
*
* @param {string|null} html The html to parse and use as the result.
* @param {number} position The position inside the source text where the item
* starts.
@@ -203,6 +211,7 @@
/**
* Does the given range overlap with anything already in the item list.
*
* @param {number} position
* @param {number} length
* @param {!Array<Defs.CommentLinkItem>} outputArray
@@ -225,6 +234,7 @@
/**
* Parse the given source text and emit callbacks for the items that are
* parsed.
*
* @param {string} text
*/
GrLinkTextParser.prototype.parse = function(text) {
@@ -240,6 +250,7 @@
* ba-linkify has found a plain URL and wants it linkified.
* - With only a `text` parameter provided: this represents the non-link
* content that lies between the links the library has found.
*
* @param {string} text
* @param {string|null|undefined} href
*/
@@ -266,6 +277,7 @@
/**
* Walk over the given source text to find matches for comemntlink patterns
* and emit parse result callbacks.
*
* @param {string} text The raw source text.
* @param {Object|null|undefined} patterns A comment links specification
* object.

2
polygerrit-ui/app/elements/shared/gr-rest-api-interface/gr-etag-decorator.js
View File

@@ -30,6 +30,7 @@
/**
* Get or upgrade fetch options to include an ETag in a request.
*
* @param {string} url The URL being fetched.
* @param {!Object=} opt_options Optional options object in which to include
* the ETag request header. If omitted, the result will be a fresh option
@@ -77,6 +78,7 @@
/**
* Get the cached payload for a given URL.
*
* @param {string} url
* @return {string|undefined} Returns the unparsed JSON payload from the
* cache.

18
polygerrit-ui/app/elements/shared/gr-rest-api-interface/gr-rest-api-interface.js
View File

@@ -43,6 +43,7 @@
* - cancelCondition is a function that, if provided and returns true, will
* cancel the response after it resolves.
* - params is a key-value hash to specify get params for the request URL.
*
* @typedef {{
* url: string,
* errFn: (function(?Response, string=)|null|undefined),
@@ -82,6 +83,7 @@
* - headers is a key-value hash to describe HTTP headers for the request.
* - parseResponse states whether the result should be parsed as a JSON
* object using getResponseObject.
*
* @typedef {{
* method: string,
* url: string,
@@ -253,6 +255,7 @@
/**
* Wraps calls to the underlying authenticated fetch function (_auth.fetch)
* with timing and logging.
*
* @param {Defs.FetchRequest} req
*/
_fetch(req) {
@@ -270,6 +273,7 @@
* Log information about a REST call. Because the elapsed time is determined
* by this method, it should be called immediately after the request
* finishes.
*
* @param {Defs.FetchRequest} req
* @param {number} startTime the time that the request was started.
* @param {number} status the HTTP status of the response. The status value
@@ -298,6 +302,7 @@
* Returns a Promise that resolves to a native Response.
* Doesn't do error checking. Supports cancel condition. Performs auth.
* Validates auth expiry errors.
*
* @param {Defs.FetchJSONRequest} req
*/
_fetchRawJSON(req) {
@@ -332,6 +337,7 @@
* Fetch JSON from url provided.
* Returns a Promise that resolves to a parsed response.
* Same as {@link _fetchRawJSON}, plus error handling.
*
* @param {Defs.FetchJSONRequest} req
*/
_fetchJSON(req) {
@@ -1293,6 +1299,7 @@
/**
* Inserts a change into _projectLookup iff it has a valid structure.
*
* @param {?{ _number: (number|string) }} change
*/
_maybeInsertInLookup(change) {
@@ -1488,6 +1495,7 @@
/**
* The closure compiler doesn't realize this.specialFilePathCompare is
* valid.
*
* @suppress {checkTypes}
*/
getChangeFilePathsAsSpeciallySortedArray(changeNum, patchRange) {
@@ -2030,6 +2038,7 @@
/**
* Gets a file in a specific change and revision.
*
* @param {number|string} changeNum
* @param {string} path
* @param {number|string} patchNum
@@ -2049,6 +2058,7 @@
/**
* Gets a file in a change edit.
*
* @param {number|string} changeNum
* @param {string} path
*/
@@ -2175,6 +2185,7 @@
/**
* Send an XHR.
*
* @param {Defs.SendRequest} req
* @return {Promise}
*/
@@ -2227,6 +2238,7 @@
/**
* Public version of the _send method preserved for plugins.
*
* @param {string} method
* @param {string} url
* @param {?string|number|Object=} opt_body passed as null sometimes
@@ -2917,6 +2929,7 @@
/**
* Alias for _changeBaseURL.then(send).
*
* @todo(beckysiegel) clean up comments
* @param {Defs.ChangeSendRequest} req
* @return {!Promise<!Object>}
@@ -2944,6 +2957,7 @@
/**
* Alias for _changeBaseURL.then(_fetchJSON).
*
* @param {Defs.ChangeFetchRequest} req
* @return {!Promise<!Object>}
*/
@@ -2966,6 +2980,7 @@
/**
* Execute a change action or revision action on a change.
*
* @param {number} changeNum
* @param {string} method
* @param {string} endpoint
@@ -2988,6 +3003,7 @@
/**
* Get blame information for the given diff.
*
* @param {string|number} changeNum
* @param {string|number} patchNum
* @param {string} path
@@ -3009,6 +3025,7 @@
/**
* Modify the given create draft request promise so that it fails and throws
* an error if the response bears HTTP status 200 instead of HTTP 201.
*
* @see Issue 7763
* @param {Promise} promise The original promise.
* @return {Promise} The modified promise.
@@ -3038,6 +3055,7 @@
/**
* Fetch a project dashboard definition.
* https://gerrit-review.googlesource.com/Documentation/rest-api-projects.html#get-dashboard
*
* @param {string} project
* @param {string} dashboard
* @param {function(?Response, string=)=} opt_errFn

5
polygerrit-ui/app/elements/shared/gr-rest-api-interface/gr-reviewer-updates-parser.js
View File

@@ -61,6 +61,7 @@
/**
* Is a part of _groupUpdates(). Creates a new batch of updates.
*
* @param {Object} update instance of ReviewerUpdateInfo
*/
GrReviewerUpdatesParser.prototype._startBatch = function(update) {
@@ -76,6 +77,7 @@
* Is a part of _groupUpdates(). Validates current batch:
* - filters out updates that don't change reviewer state.
* - updates current reviewer state.
*
* @param {Object} update instance of ReviewerUpdateInfo
*/
GrReviewerUpdatesParser.prototype._completeBatch = function(update) {
@@ -137,6 +139,7 @@
/**
* Generates update message for reviewer state change.
*
* @param {string} prev previous reviewer state.
* @param {string} state current reviewer state.
* @return {string}
@@ -158,6 +161,7 @@
/**
* Groups updates for same category (eg CC->CC) into a hash arrays of
* reviewers.
*
* @param {!Array<!Object>} updates Array of ReviewerUpdateItemInfo.
* @return {!Object} Hash of arrays of AccountInfo, message as key.
*/
@@ -175,6 +179,7 @@
/**
* Generates text messages for grouped reviewer updates.
* Formats reviewer updates to a (not yet implemented) EventInfo instance.
*
* @see https://gerrit-review.googlesource.com/c/94490/
*/
GrReviewerUpdatesParser.prototype._formatUpdates = function() {

3
polygerrit-ui/app/elements/shared/revision-info/revision-info.html
View File

@@ -32,6 +32,7 @@ limitations under the License.
* example, with normal changes this will always return 1. For merge changes
* wherein the revisions are merge commits this will return 2 or potentially
* more.
*
* @return {Number}
*/
RevisionInfo.prototype.getMaxParents = function() {
@@ -42,6 +43,7 @@ limitations under the License.
/**
* Get an object that maps revision numbers to the number of parents of the
* commit of that revision.
*
* @return {!Object}
*/
RevisionInfo.prototype.getParentCountMap = function() {
@@ -62,6 +64,7 @@ limitations under the License.
/**
* Get the commit ID of the (0-offset) indexed parent in the given revision
* number.
*
* @param {number|string} patchNum
* @param {number} parentIndex (0-offset)
* @return {string}

2
polygerrit-ui/app/lint_test.sh
View File

@@ -28,6 +28,6 @@ cd ${UI_PATH}
# Linking global eslint packages to the local project. Required to use eslint plugins with a global
# eslint installation.
npm link eslint eslint-config-google eslint-plugin-html
npm link eslint eslint-config-google eslint-plugin-html eslint-plugin-jsdoc
${eslint_bin} -c ${UI_PATH}/.eslintrc.json --ext .html,.js ${UI_PATH}