opendev/gerrit
Code Issues Proposed changes

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: Icb0533e44e17b10246f1b9d33f8d01f16a1e15a5
This commit is contained in:
Tao Zhou 2019-12-17 09:59:28 +01:00
parent 9ec2bbccc3
commit 9a07681dc2
158 changed files with 905 additions and 651 deletions
Show Stats 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",
"polymer-cli": "^1.9.11",
"typescript": "^2.x.x",

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

@ -90,13 +90,41 @@
"prefer-const": "error",
"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}
*/
@ -265,6 +266,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

@ -95,6 +95,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

@ -35,6 +35,7 @@
*/
/**
* Fired when a permission that was previously added was removed.
*
* @event added-permission-removed
*/
class GrPermission extends Polymer.mixinBehaviors( [

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

@ -356,6 +356,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

@ -96,6 +96,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

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

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

@ -214,7 +214,7 @@
/**
* Fired when an action is tapped.
*
* @event <action key>-tap
* @event custom-tap - naming pattern: <action key>-tap
*/
/**
@ -886,6 +886,7 @@
/**
* Capitalize the first letter and lowecase all others.
*
* @param {string} s
* @return {string}
*/
@ -1413,6 +1414,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

@ -401,6 +401,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

@ -942,6 +942,7 @@
/**
* Gets base patch number, if it is a parent try and decide from
* preference whether to default to `auto merge`, `Parent 1` or `PARENT`.
*
* @param {Object} change
* @param {Object} patchRange
* @return {number|string}
@ -1415,6 +1416,7 @@
/**
* Reload the change.
*
* @param {boolean=} opt_isLocationChange Reloads the related changes
* when true and ends reporting events that started on location change.
* @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

@ -183,6 +183,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

@ -538,6 +538,7 @@
/**
* The closure compiler doesn't realize this.specialFilePathCompare is
* valid.
*
* @suppress {checkTypes}
*/
_normalizeChangeFilesResponse(response) {
@ -972,6 +973,7 @@
/**
* Get a descriptive label for use in the status indicator's tooltip and
* ARIA label.
*
* @param {string} status
* @return {string}
*/
@ -1004,6 +1006,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) {
@ -1048,6 +1051,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
@ -1093,6 +1097,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)
@ -1107,6 +1112,7 @@
/**
* Reset the comments of a modified thread
*
* @param {string} rootId
* @param {string} path
*/
@ -1153,6 +1159,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) {
@ -1178,6 +1185,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}
*/
@ -1187,6 +1195,7 @@
/**
* Compute size bar layout values from the file list.
*
* @return {Gerrit.LayoutStats|undefined}
*/
_computeSizeBarLayout(shownFilesRecord) {
@ -1221,6 +1230,7 @@
/**
* Get the width of the addition bar for a file.
*
* @param {Object} file
* @param {Gerrit.LayoutStats} stats
* @return {number}
@ -1238,6 +1248,7 @@
/**
* Get the x-offset of the addition bar for a file.
*
* @param {Object} file
* @param {Gerrit.LayoutStats} stats
* @return {number}
@ -1249,6 +1260,7 @@
/**
* Get the width of the deletion bar for a file.
*
* @param {Object} file
* @param {Gerrit.LayoutStats} stats
* @return {number}
@ -1266,6 +1278,7 @@
/**
* Get the x-offset of the deletion bar for a file.
*
* @param {Gerrit.LayoutStats} stats
* @return {number}
*/
@ -1302,6 +1315,7 @@
/**
* Returns true if none of the inline diffs have been expanded.
*
* @return {boolean}
*/
_noDiffsExpanded() {
@ -1312,6 +1326,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.
*/

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

@ -129,8 +129,8 @@
}
/**
* @param label {string|undefined}
* @param permittedLabels {Object|undefined}
* @param {string|undefined} label
* @param {Object|undefined} permittedLabels
* @return {string}
*/
_computeLabelAccessClass(label, permittedLabels) {

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

@ -223,6 +223,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

@ -166,6 +166,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}
@ -227,6 +228,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
@ -244,6 +246,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

@ -641,6 +641,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

@ -110,6 +110,7 @@
/**
* Returns hash of labels to max permitted score.
*
* @param {!Object} change
* @returns {!Object} labels to max permitted scores hash
*/
@ -124,6 +125,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

@ -65,6 +65,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

@ -224,6 +224,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
@ -260,6 +261,7 @@ limitations under the License.
/**
* Generate a URL for the given route parameters.
*
* @param {Object} params
* @return {string}
*/
@ -336,6 +338,7 @@ limitations under the License.
/**
* Navigate to a search for changes with the given status.
*
* @param {string} status
*/
navigateToStatusSearch(status) {
@ -347,6 +350,7 @@ limitations under the License.
/**
* Navigate to a search query
*
* @param {string} query
* @param {number=} opt_offset
*/
@ -548,6 +552,7 @@ limitations under the License.
/**
* Navigate to an arbitrary relative URL.
*
* @param {string} relativeUrl
*/
navigateToRelativeUrl(relativeUrl) {
@ -570,6 +575,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

@ -212,6 +212,7 @@
/**
* The default reporter reports events immediately.
*
* @param {string} type
* @param {string} category
* @param {string} eventName
@ -254,6 +255,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
@ -437,6 +439,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
@ -455,6 +458,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.
*/
@ -467,6 +471,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.
*/
@ -513,6 +518,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

@ -106,6 +106,7 @@
/**
* Support vestigial params from GWT UI.
*
* @see Issue 7673.
* @type {!RegExp}
*/
@ -162,6 +163,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+)$/;
@ -547,6 +549,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}
*/
@ -613,6 +616,7 @@
/**
* Redirect the user to login using the given return-URL for redirection
* after authentication success.
*
* @param {string} returnUrl
*/
_redirectToLogin(returnUrl) {
@ -625,6 +629,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").
*/
@ -645,6 +650,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

@ -215,6 +215,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.
@ -256,6 +257,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

@ -76,6 +76,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.
@ -96,6 +97,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.
@ -117,6 +119,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

@ -408,6 +408,7 @@
/**
* Whether the given comment should be included in the base side of the
* given patch range.
*
* @param {!Object} comment
* @param {!Gerrit.PatchRange} range
* @return {boolean}
@ -439,6 +440,7 @@
/**
* Whether the given comment should be included in the revision side of the
* given patch range.
*
* @param {!Object} comment
* @param {!Gerrit.PatchRange} range
* @return {boolean}
@ -451,6 +453,7 @@
/**
* Whether the given comment should be included in the given patch range.
*
* @param {!Object} comment
* @param {!Gerrit.PatchRange} range
* @return {boolean|undefined}

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

@ -113,6 +113,7 @@ limitations under the License.
* The promise last returned from `render()` while the asynchronous
* rendering is running - `null` otherwise. Provides a `cancel()`
* method that rejects it with `{isCancelled: true}`.
*
* @type {?Object}
*/
_cancelableRenderPromise: Object,

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

@ -92,6 +92,7 @@
/**
* Abstract method
*
* @param {string} outputEl
* @param {number} fontSize
*/
@ -101,6 +102,7 @@
/**
* Abstract method
*
* @param {Object} group
*/
GrDiffBuilder.prototype.buildSectionElement = function() {
@ -469,6 +471,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}
@ -480,6 +483,7 @@
/**
* Determines whether the given group is either totally an addition or totally
* a removal.
*
* @param {!Object} group (GrDiffGroup)
* @return {boolean}
*/
@ -492,6 +496,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) {
@ -519,6 +524,7 @@
/**
* Find the blame cell for a given line number.
*
* @param {number} lineNum
* @return {HTMLTableDataCellElement}
*/
@ -531,6 +537,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.
*/
@ -550,6 +557,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.
@ -578,6 +586,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}
*/

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

@ -72,7 +72,7 @@
* to that position. This parameter should be set at most for one gr-diff
* element in the page.
*
* @type (?number)
* @type {?number}
*/
initialLineNumber: {
type: Number,
@ -201,6 +201,7 @@
/**
* Get the line number element targeted by the cursor row and side.
*
* @return {?Element|undefined}
*/
getTargetLineElement() {
@ -290,6 +291,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() {
@ -414,6 +416,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

@ -162,6 +162,7 @@
* Merges multiple ranges, accounts for triple click, accounts for
* syntax highligh, convert native DOM Range objects to Gerrit concepts
* (line, side, etc).
*
* @param {Selection} selection
* @return {({
* start: {
@ -197,6 +198,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

@ -87,6 +87,7 @@
static get is() { return 'gr-diff-host'; }
/**
* Fired when the user selects a line.
*
* @event line-selected
*/
@ -156,6 +157,7 @@
/**
* Special line number which should not be collapsed into a shared region.
*
* @type {{
* number: number,
* leftSide: {boolean}
@ -454,6 +456,7 @@
/**
* Load and display blame information for the base of the diff.
*
* @return {Promise} A promise that resolves when blame finishes rendering.
*/
loadBlame() {
@ -476,6 +479,7 @@
/**
* The thread elements in this diff, in no particular order.
*
* @return {!Array<!HTMLElement>}
*/
getThreadEls() {

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

@ -108,6 +108,7 @@
* The promise last returned from `process()` while the asynchronous
* processing is running - `null` otherwise. Provides a `cancel()`
* method that rejects it with `{isCancelled: true}`.
*
* @type {?Object}
*/
_processPromise: {
@ -139,6 +140,7 @@
/**
* Asynchronously process the diff chunks into groups. As it processes, it
* will splice groups into the `groups` property of the component.
*
* @param {!Array<!Gerrit.DiffChunk>} chunks
* @param {boolean} isBinary
* @return {!Promise<!Array<!Object>>} A promise that resolves with an
@ -464,6 +466,7 @@
* In order to show key locations, such as 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 {!Array<!Object>} chunks DiffContents as returned from server.
* @return {!Array<!Object>} Finer grained DiffContents.
*/
@ -607,6 +610,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 chunk
* or a delta it is returned as the single element of the result array.
*
* @param {!Gerrit.DiffChunk} chunk A raw chunk from a diff response.
* @return {!Array<!Array<!Object>>}
*/
@ -636,6 +640,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

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

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

@ -36,6 +36,7 @@
/**
* True means all changes in this line are whitespace changes that should
* not be highlighted as changed as per the user settings.
*
* @type{boolean}
*/
this.ignoredWhitespaceOnly = false;

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

@ -37,7 +37,7 @@
/** @type {boolean} */
this.hasIntralineInfo = false;
/** @type Array<GrDiffLine.Highlights> */
/** @type {!Array<GrDiffLine.Highlights>} */
this.highlights = [];
/** @type {?Array<Object>} ?Array<!GrDiffGroup> */

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

@ -104,6 +104,7 @@
static get is() { return 'gr-diff'; }
/**
* Fired when the user selects a line.
*
* @event line-selected
*/
@ -186,7 +187,7 @@
observer: '_viewModeObserver',
},
/** @type ?Gerrit.LineOfInterest */
/** @type {?Gerrit.LineOfInterest} */
lineOfInterest: Object,
loading: {
@ -223,7 +224,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,
@ -258,6 +259,7 @@
* Observes comment nodes added or removed after the initial render.
* Can be used to unregister when the entire diff is (re-)rendered or upon
* detachment.
*
* @type {?PolymerDomApi.ObserveHandle}
*/
_incrementalNodeObserver: Object,
@ -265,6 +267,7 @@
/**
* Observes comment nodes added or removed at any point.
* Can be used to unregister upon detachment.
*
* @type {?PolymerDomApi.ObserveHandle}
*/
_nodeObserver: Object,
@ -610,6 +613,7 @@
/**
* Gets or creates a comment thread group for a specific line and side on a
* diff.
*
* @param {!Object} contentEl
* @param {!Gerrit.DiffSide} commentSide
* @return {!Node}
@ -909,6 +913,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.
@ -945,6 +950,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.
@ -995,6 +1001,7 @@
/**
* Get the approximate length of the diff as the sum of the maximum
* length of the chunks.
*
* @param {Object} diff object
* @return {number}
*/

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

@ -186,6 +186,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

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

@ -63,6 +63,7 @@
/**
* Layer method to add annotations to a line.
*
* @param {!HTMLElement} el The DIV.contentText element to apply the
* annotation to.
* @param {!HTMLElement} lineNumberEl
@ -90,6 +91,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.
@ -100,6 +102,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')
@ -113,6 +116,7 @@
/**
* Handle change in the ranges by updating the ranges maps and by
* emitting appropriate update notifications.
*
* @param {Object} record The change record.
*/
_handleCommentRangesChange(record) {

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

@ -166,6 +166,7 @@
* The promise last returned from `process()` while the asynchronous
* processing is running - `null` otherwise. Provides a `cancel()`
* method that rejects it with `{isCancelled: true}`.
*
* @type {?Object}
*/
_processPromise: {
@ -187,6 +188,7 @@
/**
* Annotation layer method to add syntax annotations to the given element
* for the given line.
*
* @param {!HTMLElement} el
* @param {!HTMLElement} lineNumberEl
* @param {!Object} line (GrDiffLine)
@ -231,6 +233,7 @@
/**
* Start processing syntax for the loaded diff and notify layer listeners
* as syntax info comes online.
*
* @return {Promise}
*/
process() {
@ -328,6 +331,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.
* @param {Map<string, !Array<!Object>>} rangesCache A map for caching
* ranges for each string. A cache is read and written by this method.
@ -372,6 +376,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, rangesCache) {
@ -488,6 +493,7 @@
/**
* Tells whether the state has exhausted its current section.
*
* @param {!Object} state
* @return {boolean}
*/
@ -504,6 +510,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

@ -117,6 +117,7 @@
/**
* Given a path string, checks that it is a valid file path.
*
* @param {string} path
* @return {boolean}
*/
@ -131,6 +132,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-element.js
View File

@ -53,6 +53,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

@ -36,6 +36,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: {

5
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.
@ -35,6 +36,7 @@
/**
* Alias of onClick
*
* @see onClick
*/
GrEventHelper.prototype.onTap = function(callback) {
@ -44,6 +46,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.
*/
@ -53,6 +56,7 @@
/**
* Alias of captureClick
*
* @see captureClick
*/
GrEventHelper.prototype.captureTap = function(callback) {
@ -64,6 +68,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() {

3
polygerrit-ui/app/elements/plugins/gr-styles-api/gr-styles-api.js
View File

@ -33,6 +33,7 @@
* if it hasn't been added yet. A root node is an document or is the
* associated shadowRoot. This class can be added to any element with the same
* root node.
*
* @param {HTMLElement} element The element to get class name for.
* @return {string} Appropriate class name for the element is returned
*/
@ -56,6 +57,7 @@
/**
* Apply shared style to the element.
*
* @param {HTMLElement} element The element to apply style for
*/
GrStyleObject.prototype.apply = function(element) {
@ -67,6 +69,7 @@
/**
* Creates a new GrStyleObject with specified style properties.
*
* @param {string} String with style properties.
* @return {GrStyleObject}
*/

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

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

3
polygerrit-ui/app/elements/shared/gr-account-list/gr-account-list.js
View File

@ -52,6 +52,7 @@
/**
* Returns suggestions and convert them to list item
*
* @type {Gerrit.GrSuggestionsProvider}
*/
suggestionsProvider: {
@ -60,6 +61,7 @@
/**
* Needed for template checking since value is initially set to null.
*
* @type {?Object}
*/
pendingConfirmation: {
@ -91,6 +93,7 @@
/**
* Returns suggestion items
*
* @type {!function(string): Promise<Array<Gerrit.GrSuggestionItem>>}
*/
_querySuggestions: {

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

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

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

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

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

@ -37,7 +37,7 @@
observer: '_updateIndex',
},
/**
* @type (?Object)
* @type {?Object}
*/
target: {
type: Object,
@ -46,7 +46,8 @@
},
/**
* The height of content intended to be included with the target.
* @type (?number)
*
* @type {?number}
*/
_targetHeight: Number,
@ -72,7 +73,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,
@ -96,6 +98,7 @@
/**
* Move the cursor forward. Clipped to the ends of the stop list.
*
* @param {!Function=} opt_condition Optional stop condition. If a condition
* is passed the cursor will continue to move in the specified direction
* until the condition is met.
@ -117,6 +120,7 @@
/**
* Set the cursor to an arbitrary element.
*
* @param {!HTMLElement} element
* @param {boolean=} opt_noScroll prevent any potential scrolling in response
* setting the cursor.
@ -164,6 +168,7 @@
/**
* Move the cursor forward or backward by delta. Clipped to the beginning or
* end of 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
@ -220,6 +225,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.
* @param {boolean=} opt_clipToTop When none of the next indices match, move
@ -270,6 +276,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

@ -82,6 +82,7 @@
/**
* Handle a click on the iron-dropdown element.
*
* @param {!Event} e
*/
_handleDropdownClick(e) {
@ -94,6 +95,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

@ -99,6 +99,7 @@
/**
* Handle the up key.
*
* @param {!Event} e
*/
_handleUp(e) {
@ -113,6 +114,7 @@
/**
* Handle the down key.
*
* @param {!Event} e
*/
_handleDown(e) {
@ -127,6 +129,7 @@
/**
* Handle the tab key.
*
* @param {!Event} e
*/
_handleTab(e) {
@ -139,6 +142,7 @@
/**
* Handle the enter key.
*
* @param {!Event} e
*/
_handleEnter(e) {
@ -157,6 +161,7 @@
/**
* Handle a click on the iron-dropdown element.
*
* @param {!Event} e
*/
_handleDropdownClick(e) {
@ -165,6 +170,7 @@
/**
* Hanlde a click on the button to open the dropdown.
*
* @param {!Event} e
*/
_dropdownTriggerTapHandler(e) {
@ -197,6 +203,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.
*/
@ -207,6 +214,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.
@ -221,6 +229,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.
*/
@ -231,6 +240,7 @@
/**
* Compute the URL for a link object.
*
* @param {!Object} link The object describing the link.
* @return {!string} The URL.
*/
@ -248,6 +258,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.
*/
@ -260,6 +271,7 @@
/**
* Handle a click on an item of the dropdown.
*
* @param {!Event} e
*/
_handleItemTap(e) {
@ -275,6 +287,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

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

3
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} contentEl The DIV.contentText element of the line
* content to apply the annotation to using annotateRange.
* @param {HTMLElement} lineNumberEl The TD element of the line number to
@ -41,6 +42,7 @@
/**
* Method to add annotations to a content line.
*
* @param {number} offset The char offset where the update starts.
* @param {number} length The number of chars that the update covers.
* @param {GrStyleObject} styleObject The style object for the range.
@ -56,6 +58,7 @@
/**
* Method to add a CSS class to the line number TD element.
*
* @param {GrStyleObject} styleObject The style object for the range.
* @param {string} side The side of the update. ('left' or 'right')
*/

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

@ -37,6 +37,7 @@
* GrAnnotationActionsContext.annotateRange and
* GrAnnotationActionsContext.annotateLineNumber to apply a CSS class to the
* line content or the line number.
*
* @param {function(GrAnnotationActionsContext)} addLayerFunc The function
* that will be called when the AnnotationLayer is ready to annotate.
*/
@ -48,6 +49,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.
*/
@ -129,6 +131,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.
@ -149,6 +152,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.
@ -163,6 +167,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.
@ -180,6 +185,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.
@ -190,6 +196,7 @@
/**
* Layer method to add annotations to a line.
*
* @param {HTMLElement} contentEl The DIV.contentText element of the line
* content to apply the annotation to using annotateRange.
* @param {HTMLElement} lineNumberEl The TD element of the line number to
@ -205,6 +212,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')

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

@ -35,6 +35,7 @@
/**
* Retrieves the name of the plugin base on the url.
*
* @param {string|URL} url
*/
function getPluginNameFromUrl(url) {

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

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

4
polygerrit-ui/app/elements/shared/gr-js-api-interface/gr-plugin-loader.js
View File

@ -95,6 +95,7 @@
/**
* Use the plugin name or use the full url if not recognized.
*
* @see gr-api-utils#getPluginNameFromUrl
* @param {string|URL} url
*/
@ -283,6 +284,7 @@
/**
* Checks if given plugin path/url is enabled or not.
*
* @param {string} pathOrUrl
*/
isPluginEnabled(pathOrUrl) {
@ -294,6 +296,7 @@
/**
* Returns the plugin object with a given url.
*
* @param {string} pathOrUrl
*/
getPlugin(pathOrUrl) {
@ -303,6 +306,7 @@
/**
* Checks if given plugin path/url is loaded or not.
*
* @param {string} pathOrUrl
*/
isPluginLoaded(pathOrUrl) {

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

@ -61,6 +61,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.
@ -76,6 +77,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.

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

@ -222,6 +222,7 @@
/**
* To make REST requests for plugin-provided endpoints, use
*
* @example
* const pluginRestApi = plugin.restApi(plugin.url());
*

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

@ -44,6 +44,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() {
@ -68,6 +69,7 @@
/**
* Loads the dark theme document. Returns a promise that resolves with a
* custom-style DOM element.
*
* @return {!Promise<Element>}
* @suppress {checkTypes}
*/
@ -103,6 +105,7 @@
/**
* Get the HLJS library, assuming it has been loaded. Configure the library
* if it hasn't already been configured.
*
* @return {!Object}
*/
_getHighlightLib() {
@ -118,6 +121,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() {
@ -129,6 +133,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-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.

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

@ -1004,6 +1004,7 @@
/**
* Inserts a change into _projectLookup iff it has a valid structure.
*
* @param {?{ _number: (number|string) }} change
*/
_maybeInsertInLookup(change) {
@ -1206,6 +1207,7 @@
/**
* The closure compiler doesn't realize this.specialFilePathCompare is
* valid.
*
* @suppress {checkTypes}
*/
getChangeFilePathsAsSpeciallySortedArray(changeNum, patchRange) {
@ -1766,6 +1768,7 @@
/**
* Gets a file in a specific change and revision.
*
* @param {number|string} changeNum
* @param {string} path
* @param {number|string} patchNum
@ -1785,6 +1788,7 @@
/**
* Gets a file in a change edit.
*
* @param {number|string} changeNum
* @param {string} path
*/
@ -1911,6 +1915,7 @@
/**
* Public version of the _restApiHelper.send method preserved for plugins.
*
* @param {string} method
* @param {string} url
* @param {?string|number|Object=} opt_body passed as null sometimes
@ -2603,6 +2608,7 @@
/**
* Alias for _changeBaseURL.then(send).
*
* @todo(beckysiegel) clean up comments
* @param {Gerrit.ChangeSendRequest} req
* @return {!Promise<!Object>}
@ -2630,6 +2636,7 @@
/**
* Alias for _changeBaseURL.then(_fetchJSON).
*
* @param {Gerrit.ChangeFetchRequest} req
* @return {!Promise<!Object>}
*/
@ -2652,6 +2659,7 @@
/**
* Execute a change action or revision action on a change.
*
* @param {number} changeNum
* @param {string} method
* @param {string} endpoint
@ -2674,6 +2682,7 @@
/**
* Get blame information for the given diff.
*
* @param {string|number} changeNum
* @param {string|number} patchNum
* @param {string} path
@ -2695,6 +2704,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.
@ -2724,6 +2734,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-rest-apis/gr-rest-api-helper.js
View File

@ -122,6 +122,7 @@
/**
* Wraps calls to the underlying authenticated fetch function (_auth.fetch)
* with timing and logging.
*
* @param {Gerrit.FetchRequest} req
*/
fetch(req) {
@ -139,6 +140,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 {Gerrit.FetchRequest} req
* @param {number} startTime the time that the request was started.
* @param {number} status the HTTP status of the response. The status value
@ -171,6 +173,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 {Gerrit.FetchJSONRequest} req
*/
fetchRawJSON(req) {
@ -205,6 +208,7 @@
* Fetch JSON from url provided.
* Returns a Promise that resolves to a parsed response.
* Same as {@link fetchRawJSON}, plus error handling.
*
* @param {Gerrit.FetchJSONRequest} req
*/
fetchJSON(req) {
@ -329,6 +333,7 @@
/**
* Send an XHR.
*
* @param {Gerrit.SendRequest} req
* @return {Promise}
*/

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

@ -60,6 +60,7 @@
/**
* Is a part of _groupUpdates(). Creates a new batch of updates.
*
* @param {Object} update instance of ReviewerUpdateInfo
*/
GrReviewerUpdatesParser.prototype._startBatch = function(update) {
@ -75,6 +76,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) {
@ -136,6 +138,7 @@
/**
* Generates update message for reviewer state change.
*
* @param {string} prev previous reviewer state.
* @param {string} state current reviewer state.
* @return {string}
@ -157,6 +160,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.
*/
@ -174,6 +178,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() {
@ -45,6 +46,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() {
@ -68,6 +70,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

@ -35,6 +35,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 --ignore-pattern 'node_modules/' --ignore-pattern 'bower_components/' --ignore-pattern 'gr-linked-text' --ignore-pattern 'scripts/vendor' --ext .html,.js ${UI_PATH}

3
polygerrit-ui/app/types/types.js
View File

@ -99,6 +99,7 @@ Gerrit.ChangeFetchRequest;
* - 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,
@ -146,6 +147,7 @@ Gerrit.FetchRequest;
* - 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),
@ -217,6 +219,7 @@ Gerrit.CommentsBySide;
* Note that the implied newline character at the end of each line is included
* in the length calculation, and thus it is possible for the edits to span
* newlines.
*
* @typedef {!Array<number>}
*/
Gerrit.IntralineInfo;