Add Media Router JS structs.

chrome/browser/resources/media_router/media_router_data.js

+// Copyright (c) 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+cr.define('media_router', function() {
+  'use strict';
+
+  /**
+   * @param {number} castMode The type of cast mode.

[mark a. foltz, 2015/03/24 18:09:16]

Where are legal values defined?

[apacible, 2015/03/24 20:46:26]

RE: all legal values questions --
These are all defined in Media Router, but not all landed in Chromium yet. Some
are also defined in the component extension (depending on whether we pass them
from the CE to MR).

+   * @param {string} title The title of the cast mode.

[mark a. foltz, 2015/03/24 18:09:17]

Is the title and description for internal use, or are they shown to the user? 
If the latter, how would the WebUI page map them to a localized resource? 

[apacible, 2015/03/24 20:46:26]

The description is shown.

RE: all localization questions --
All of the strings are localized in Media Router before being passed to the
WebUI. No localization will be done from the WebUI side.

+   * @param {string} description The description of the cast mode.
+   * @constructor
+   * @struct
+   */
+  var CastMode = function(castMode, title, description) {
+    /** @type {number} */
+    this.castMode = castMode;
+
+    /** @type {string} */
+    this.title = title;
+
+    /** @type {string} */
+    this.description = description;
+  };
+
+  /**

[James Hawkins, 2015/03/24 17:48:06]

nit: Double blank lines between top-level JSDoc blocks.

[apacible, 2015/03/24 20:46:26]

Done.

+   * @param {string} id The ID of this issue.

[mark a. foltz, 2015/03/24 18:09:15]

What are legal values?  Are these defined somewhere?

[apacible, 2015/03/24 20:46:26]

Issue IDs are created in Media Router using GenerateGUID.

+   * @param {string} title The issue title.

[mark a. foltz, 2015/03/24 18:09:16]

Similar questions about localization for all the strings passed in here.

[apacible, 2015/03/24 20:46:27]

Acknowledged.

+   * @param {string} message The issue message.
+   * @param {string} defaultActionText The button text of default action.

[mark a. foltz, 2015/03/24 18:09:16]

What if the text overflows the dimensions of the button?

[apacible, 2015/03/24 20:46:26]

We'll need to talk to UX about this (and all other potentially overflowing
text). Since we're looking into some proposed redesigns right now, this will be
something I'll bring up with Jonny. Our final designs should take this into
account.

+   * @param {number} defaultActionType The type of default action.

[mark a. foltz, 2015/03/24 18:09:16]

Where are the types defined?

[apacible, 2015/03/24 20:46:26]

Acknowledged.

+   * @param {?string} optActionText The button text of optional action.
+   * @param {?number} optActionType The type of optional action.

[mark a. foltz, 2015/03/24 18:09:16]

Where are the types defined?

[apacible, 2015/03/24 20:46:26]

Acknowledged.

+   * @param {?string} routeId The route ID to which this issue

[mark a. foltz, 2015/03/24 18:09:17]

mediaRouteId

[apacible, 2015/03/24 20:46:26]

Done.

+   *                  pertains. If not set, this is a global issue.

[mark a. foltz, 2015/03/24 18:09:16]

What if the issue occurred before or after the route was created?
Should this be a screenId instead?

[apacible, 2015/03/24 20:46:26]

We currently don't have screen-specific issues. If the issue occurs before any
route was created, it would be a global issue. If an issue occurs after (or as)
a route is created, it could be either route-specific or global.

+   * @param {boolean} isBlocking True if this issue blocks other UI.
+   * @param {?string} helpURL The URL to be opened if learn more is clicked.
+   * @constructor
+   * @struct
+   */
+  var Issue = function(id, title, message, defaultActionText,
+                       defaultActionType, optActionText, optActionType,

[James Hawkins, 2015/03/24 17:48:06]

nit: opt_actionText, opt_actionType

[apacible, 2015/03/24 20:46:26]

Ack, question in next comment before I change this.

+                       routeId, isBlocking, helpURL) {
+    /** @type {string} */
+    this.id = id;
+
+    /** @type {string} */
+    this.title = title;
+
+    /** @type {string} */
+    this.message = message;
+
+    /** @type {string} */
+    this.defaultActionText = defaultActionText;
+
+    /** @type {number} */
+    this.defaultActionType = defaultActionType;
+
+    /** @type {?string} */
+    this.optActionText = optActionText;

[James Hawkins, 2015/03/24 17:48:06]

nit: Only the parameter should have 'opt' in the name.

[apacible, 2015/03/24 20:46:26]

Why is 'opt' restricted to the parameter?

Should I rename this to 'secondaryActionText'? There's a 'default' action text
and an 'optional/secondary' action text.

[James Hawkins, 2015/03/24 21:27:56]

Because the member variable itself is not optional; it exists for each object
instance. It may be null, but that is documented by its type.

secondaryActionText seems fine to me, but that's your call.

[apacible, 2015/03/24 21:58:11]

Thanks! Also, should I prepend all optional parameters with opt_*, or is that
only the convention if 'opt' is used somewhere in the parameter? (e.g. using
@param secondaryActionText and then this.secondaryActionText is fine)

+
+    /** @type {?number} */
+    this.optActionType = optActionType;
+
+    /** @type {?string} */
+    this.routeId = routeId;
+
+    /** @type {boolean} */
+    this.isBlocking = isBlocking;
+
+    /** @type {?string} */
+    this.helpURL = helpURL;
+  };
+
+  /**
+   * @param {string} id The route ID.

[mark a. foltz, 2015/03/24 18:09:15]

The media route ID

[apacible, 2015/03/24 20:46:26]

Done.

+   * @param {string} sinkId The ID of the sink running this route.

[mark a. foltz, 2015/03/24 18:09:15]

"the media sink"

[apacible, 2015/03/24 20:46:26]

Done.

+   * @param {?string} iconUrl The icon URL of this route.

[mark a. foltz, 2015/03/24 18:09:16]

This should just point to a bundled resource, correct?  Can this just be an enum
that references one of those instead of an arbitrary URL?

[apacible, 2015/03/24 20:46:27]

This is the favicon of whatever we're casting. Talked to haibinlu@ -- I'm
removing this for now since we're not 100% sure what our UX for mirroring will
be. Bringing this up with Jonny as well.

+   * @param {string} title The short description of this route.
+   * @param {?number} tabId The ID of the tab in which web app is running and
+   *                        accessing the route.
+   * @param {boolean} isLocal True if this is a locally launched route.

[mark a. foltz, 2015/03/24 18:09:16]

s/launched/created/

[apacible, 2015/03/24 20:46:27]

Done.

+   * @constructor
+   * @struct
+   */
+  var Route = function(id, sinkId, iconUrl, title, tabId, isLocal) {
+    /** @type {string} */
+    this.id = id;
+
+    /** @type {string} */
+    this.sinkId = sinkId;
+
+    /** @type {?string} */
+    this.iconUrl = iconUrl;
+
+    /** @type {string} */
+    this.title = title;
+
+    /** @type {?number} */
+    this.tabId = tabId;
+
+    /** @type {boolean} */
+    this.isLocal = isLocal;
+  };
+
+  /**
+   * @param {string} id The ID of the sink.

[mark a. foltz, 2015/03/24 18:09:17]

"the media sink"

[apacible, 2015/03/24 20:46:26]

Done.

+   * @param {string} name The name of the sink.
+   * @param {media_router.SinkStatus} status The readiness state of the sink.
+   * @param {!Array<number>} castModes Cast modes compatible with the sink.
+   * @constructor
+   * @struct
+   */
+  var Sink = function(id, name, status) {
+    /** @type {string} */
+    this.id = id;
+
+    /** @type {string} */
+    this.name = name;
+
+    /** @type {media_router.SinkStatus} */
+    this.status = status;
+
+    /** @type {!Array<number>} */
+    this.castModes = castModes;
+  };
+
+  /**
+   * @enum {string}
+   */
+  var SinkStatus = {

[James Hawkins, 2015/03/24 17:48:06]

Consider moving SinkStatus higher up (at least higher than where it's first
used.  Grouping definitions by type would have this go at the very top, but it's
up to you.

[apacible, 2015/03/24 20:46:26]

Moved to top.

+    IDLE: 'idle',
+    ACTIVE: 'active',
+    REQUEST_PENDING: 'request_pending'
+  };
+
+  /**
+   * @param {number} tabId The current tab ID.
+   * @param {string} domain The domain of the current tab.
+   * @param {boolean} hasCastApp True if tab has a current Cast App.

[mark a. foltz, 2015/03/24 18:09:16]

When is this set to true?  Does it mean to say "an active media route"?

[apacible, 2015/03/24 20:46:26]

It's when the tab has a current cast app (e.g. YouTube) so we know which cast
modes to show.

Talked to imcheng@/haibinlu@ -- removing this because we don't need this
anymore.

+   * @constructor
+   * @struct
+   */
+  var TabInfo = function(tabId, domain, hasCastApp) {
+    /** @type {number} */
+    this.tabId = tabId;
+
+    /** @type {string} */
+    this.domain = domain;
+
+    /** @type {boolean} */
+    this.hasCastApp = hasCastApp;
+  };
+
+  return {
+    CastMode: CastMode,
+    Issue: Issue,
+    Route: Route,
+    Sink: Sink,
+    SinkStatus: SinkStatus,
+    TabInfo: TabInfo,
+  };
+});