DevTools: Add JSDoc for static methods, fix JSDoc types and induced errors

DevTools: Add JSDoc for static methods, fix JSDoc types and induced errors

This patch adds JSDoc for "WebInspector.Foo.bar" methods and fixes
induced errors:
- adds typecasts where required;
- removes unused code violating JSDoc, which was not checked previously;
- adds missing "useCapture" addEventListener() arguments (they are
  required by the current compiler and will be fixed after the
  compiler roll).

R=yurys@chromium.org, vsevik, yurys

Committed: https://src.chromium.org/viewvc/blink?view=rev&revision=176325

[yurys, 2014-06-17 11:32:29]

lgtm

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/Sc...
File Source/devtools/front_end/ScreencastView.js (right):

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/Sc...
Source/devtools/front_end/ScreencastView.js:252: * @param {?Event} event
When can event be null?

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/au...
File Source/devtools/front_end/audits/AuditsPanel.js (right):

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/au...
Source/devtools/front_end/audits/AuditsPanel.js:377: * @return {string}
add @param annotation?

[aandrey, 2014-06-17 11:33:55]

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/au...
File Source/devtools/front_end/audits/AuditsPanel.js (right):

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/au...
Source/devtools/front_end/audits/AuditsPanel.js:377: * @return {string}
@param {string} domain

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/co...
File Source/devtools/front_end/common/utilities.js (right):

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/co...
Source/devtools/front_end/common/utilities.js:989: * @param {function(?, ?):
T|undefined} append
function(T, string)

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/co...
File Source/devtools/front_end/components/TimelineGrid.js (right):

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/co...
Source/devtools/front_end/components/TimelineGrid.js:194: var divider = /**
@type {?Element} */ (this._dividersElement.firstChild);
why this cast? looks like some other place should be fixed.

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/el...
File Source/devtools/front_end/elements/StylesSidebarPane.js (right):

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/el...
Source/devtools/front_end/elements/StylesSidebarPane.js:2710: selectElement =
/** @type {?Element} */
(selectElement.enclosingNodeOrSelfWithClass("webkit-css-property") ||
selectElement.enclosingNodeOrSelfWithClass("value"));
why this cast?

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/pr...
File Source/devtools/front_end/profiler/HeapSnapshotView.js (right):

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/pr...
Source/devtools/front_end/profiler/HeapSnapshotView.js:33: * @suppress
{es5Strict}
put a comment or FIXME why suppressing

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/re...
File Source/devtools/front_end/resources/DirectoryContentView.js (right):

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/re...
Source/devtools/front_end/resources/DirectoryContentView.js:104: * @return
{function(*, *):number|undefined}
why * instead of types?

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/sc...
File Source/devtools/front_end/script_formatter_worker/ScriptFormatterWorker.js
(right):

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/sc...
Source/devtools/front_end/script_formatter_worker/ScriptFormatterWorker.js:484:
* @suppress {duplicate}
why suppress?

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/ti...
File Source/devtools/front_end/timeline/TimelineView.js (right):

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/ti...
Source/devtools/front_end/timeline/TimelineView.js:655: var element = /** @type
{?Element} */ (container.firstChild);
should be no cast

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/ui...
File Source/devtools/front_end/ui/SidebarPane.js (right):

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/ui...
Source/devtools/front_end/ui/SidebarPane.js:129:
this._pane.show(this.element.parentElement, /** @type {?Element} */
(this.element.nextSibling));
should be no cast (e.g. let pane.show() accept undefined)

https://codereview.chromium.org/340513003/diff/1/Source/devtools/scripts/comp...
File Source/devtools/scripts/compile_frontend.py (right):

https://codereview.chromium.org/340513003/diff/1/Source/devtools/scripts/comp...
Source/devtools/scripts/compile_frontend.py:95: invalid_type_designator_regex =
re.compile(r"@(?:" + type_checked_jsdoc_tags_or + r")\s*.*(?<![{: ])([?!])=?\}")
hard to review

[apavlov, 2014-06-17 12:46:04]

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/Sc...
File Source/devtools/front_end/ScreencastView.js (right):

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/Sc...
Source/devtools/front_end/ScreencastView.js:252: * @param {?Event} event
On 2014/06/17 11:32:28, yurys wrote:
> When can event be null?

This is how it is specified in the compiler own externs

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/au...
File Source/devtools/front_end/audits/AuditsPanel.js (right):

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/au...
Source/devtools/front_end/audits/AuditsPanel.js:377: * @return {string}
On 2014/06/17 11:33:54, aandrey wrote:
> @param {string} domain

Done.

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/co...
File Source/devtools/front_end/common/utilities.js (right):

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/co...
Source/devtools/front_end/common/utilities.js:989: * @param {function(?, ?):
T|undefined} append
On 2014/06/17 11:33:54, aandrey wrote:
> function(T, string)

Done.

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/co...
File Source/devtools/front_end/components/TimelineGrid.js (right):

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/co...
Source/devtools/front_end/components/TimelineGrid.js:194: var divider = /**
@type {?Element} */ (this._dividersElement.firstChild);
On 2014/06/17 11:33:54, aandrey wrote:
> why this cast? looks like some other place should be fixed.

firstChild returns {?Node}, but given the fact that we construct the DOM
manually, it must be an {?Element}. I'm not sure if the firstElementChild getter
will be semantically equivalent. We can fix this later if need be.

The same holds for other firstChild-related casts.

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/el...
File Source/devtools/front_end/elements/StylesSidebarPane.js (right):

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/el...
Source/devtools/front_end/elements/StylesSidebarPane.js:2710: selectElement =
/** @type {?Element} */
(selectElement.enclosingNodeOrSelfWithClass("webkit-css-property") ||
selectElement.enclosingNodeOrSelfWithClass("value"));
On 2014/06/17 11:33:54, aandrey wrote:
> why this cast?

Thanks, refined the return type

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/pr...
File Source/devtools/front_end/profiler/HeapSnapshotView.js (right):

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/pr...
Source/devtools/front_end/profiler/HeapSnapshotView.js:33: * @suppress
{es5Strict}
On 2014/06/17 11:33:54, aandrey wrote:
> put a comment or FIXME why suppressing

Done.

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/re...
File Source/devtools/front_end/resources/DirectoryContentView.js (right):

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/re...
Source/devtools/front_end/resources/DirectoryContentView.js:104: * @return
{function(*, *):number|undefined}
On 2014/06/17 11:33:54, aandrey wrote:
> why * instead of types?

Done.

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/sc...
File Source/devtools/front_end/script_formatter_worker/ScriptFormatterWorker.js
(right):

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/sc...
Source/devtools/front_end/script_formatter_worker/ScriptFormatterWorker.js:484:
* @suppress {duplicate}
On 2014/06/17 11:33:54, aandrey wrote:
> why suppress?

Thanks for spotting - it is already found in utilities.js, so I'm removing this
replica.

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/ti...
File Source/devtools/front_end/timeline/TimelineView.js (right):

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/ti...
Source/devtools/front_end/timeline/TimelineView.js:655: var element = /** @type
{?Element} */ (container.firstChild);
On 2014/06/17 11:33:54, aandrey wrote:
> should be no cast

same as above

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/ui...
File Source/devtools/front_end/ui/SidebarPane.js (right):

https://codereview.chromium.org/340513003/diff/1/Source/devtools/front_end/ui...
Source/devtools/front_end/ui/SidebarPane.js:129:
this._pane.show(this.element.parentElement, /** @type {?Element} */
(this.element.nextSibling));
On 2014/06/17 11:33:54, aandrey wrote:
> should be no cast (e.g. let pane.show() accept undefined)

This cast is about Node->Element, not about undefined->null

[apavlov, 2014-06-17 14:44:40]

The CQ bit was checked by apavlov@chromium.org

[commit-bot: I haz the power, 2014-06-17 14:45:03]

CQ is trying da patch. Follow status at
 https://chromium-status.appspot.com/cq/apavlov@chromium.org/340513003/40001

[apavlov, 2014-06-17 16:00:06]

Committed patchset #4 manually as r176325 (presubmit successful).