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

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

package.json

@@ -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",

polygerrit-ui/app/.eslintrc.json

@@ -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"

polygerrit-ui/app/behaviors/docs-url-behavior/docs-url-behavior.html

@@ -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

polygerrit-ui/app/behaviors/dom-util-behavior/dom-util-behavior.html

@@ -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

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

@@ -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.

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

@@ -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}
      */

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

@@ -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}
      */

polygerrit-ui/app/behaviors/safe-types-behavior/safe-types-behavior.html

@@ -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() {

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

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

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

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

polygerrit-ui/app/elements/admin/gr-permission/gr-permission.js

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

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

@@ -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]);

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

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

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

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

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

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

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

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

polygerrit-ui/app/elements/change/gr-change-actions/gr-change-actions.js

@@ -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

polygerrit-ui/app/elements/change/gr-change-metadata/gr-change-metadata.js

@@ -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.

polygerrit-ui/app/elements/change/gr-change-view/gr-change-view.js

@@ -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.

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

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

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

@@ -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.
      */

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

@@ -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.

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

@@ -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
      *

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

@@ -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}
      */

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

@@ -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

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

@@ -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) {

polygerrit-ui/app/elements/core/gr-navigation/gr-navigation.html

@@ -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) {

polygerrit-ui/app/elements/core/gr-reporting/gr-reporting.js

@@ -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.
      */

polygerrit-ui/app/elements/core/gr-router/gr-router.js

@@ -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).

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

@@ -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.

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

@@ -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.

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

@@ -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}

polygerrit-ui/app/elements/diff/gr-diff-builder/gr-diff-builder.html

@@ -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() {

polygerrit-ui/app/elements/diff/gr-diff-builder/gr-diff-builder.js

@@ -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}
    */

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

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

polygerrit-ui/app/elements/diff/gr-diff-cursor/gr-diff-cursor.js

@@ -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) {

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

@@ -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.
      */

polygerrit-ui/app/elements/diff/gr-diff-highlight/gr-diff-highlight.js

@@ -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) {

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

@@ -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.
      */

polygerrit-ui/app/elements/diff/gr-diff-host/gr-diff-host.js

@@ -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}
      */

polygerrit-ui/app/elements/diff/gr-diff-processor/gr-diff-processor.js

@@ -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>>}

polygerrit-ui/app/elements/diff/gr-diff-selection/gr-diff-selection.js

@@ -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) {

polygerrit-ui/app/elements/diff/gr-diff/gr-diff.js

@@ -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.

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

@@ -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

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

@@ -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.

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

@@ -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) {

polygerrit-ui/app/elements/edit/gr-edit-controls/gr-edit-controls.js

@@ -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}
      */

polygerrit-ui/app/elements/gr-app.js

@@ -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: {

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

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

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

@@ -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) {

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

@@ -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: {

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

@@ -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.
    */

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

@@ -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() {

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

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

polygerrit-ui/app/elements/shared/gr-autocomplete/gr-autocomplete.js

@@ -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) {

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

@@ -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.
      */

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

@@ -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) {

polygerrit-ui/app/elements/shared/gr-dropdown/gr-dropdown.js

@@ -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.

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

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

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

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

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

@@ -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.

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

@@ -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')

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

@@ -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
    */

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

@@ -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) {

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

@@ -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),

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

@@ -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.

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

@@ -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) {

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

@@ -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.

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

@@ -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

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

@@ -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.

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

@@ -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.

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

@@ -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

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

@@ -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() {

polygerrit-ui/app/elements/shared/revision-info/revision-info.html

@@ -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}

polygerrit-ui/app/lint_test.sh

@@ -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}