Restrict deprecated parts of audio API usage to whitelisted apps

extensions/common/api/audio.idl

Index: extensions/common/api/audio.idl
diff --git a/extensions/common/api/audio.idl b/extensions/common/api/audio.idl
index 69b36d84937b4f45b1b727174ef82617b6690bde..5f25ee161afbafc3c13ba748859bd49fbb2e7712 100644
--- a/extensions/common/api/audio.idl
+++ b/extensions/common/api/audio.idl
@@ -32,7 +32,7 @@ namespace audio {
     OTHER
   };
 
-  [deprecated = "Used only with the deprecated $(ref:getInfo)."]
+  [nodoc, deprecated = "Used only with the deprecated $(ref:getInfo)."]
   dictionary OutputDeviceInfo {
     // The unique identifier of the audio output device.
     DOMString id;
@@ -46,7 +46,7 @@ namespace audio {
     double volume;
   };
 
-  [deprecated = "Used only with the deprecated $(ref:getInfo)."]
+  [nodoc, deprecated = "Used only with the deprecated $(ref:getInfo)."]
   dictionary InputDeviceInfo {
     // The unique identifier of the audio input device.
     DOMString id;
@@ -65,8 +65,6 @@ namespace audio {
     DOMString id;
     // Stream type associated with this device.
     StreamType streamType;
-    // True for input device; false for output device.
-    [deprecated="Use |streamType|."] boolean isInput;

[tbarzic, 2017/02/16 00:42:55]

Note that AudioDeviceInfo is not currently in use anywhere, so this should be
safe.

     // Type of the device.
     DeviceType deviceType;
     // The user-friendly name (e.g. "USB Microphone").
@@ -75,8 +73,6 @@ namespace audio {
     DOMString deviceName;
     // True if this is the current active device.
     boolean isActive;
-    // True if this is muted.
-    boolean isMuted;
     // The sound level of the device, volume for output, gain for input.
     long level;
     // The stable/persisted device id string when available.
@@ -95,15 +91,16 @@ namespace audio {
 
   dictionary DeviceProperties {
     // True if this is muted.
-    [deprecated="Use $(ref:setMute) to set mute state."] boolean? isMuted;
+    [nodoc, deprecated="Use $(ref:setMute) to set mute state."]
+    boolean? isMuted;
 
     // If this is an output device then this field indicates the output volume.
     // If this is an input device then this field is ignored.
-    [deprecated="Use |level| to set output volume."] double? volume;
+    [nodoc, deprecated="Use |level| to set output volume."] double? volume;
 
     // If this is an input device then this field indicates the input gain.
     // If this is an output device then this field is ignored.
-    [deprecated="Use |level| to set input gain."] double? gain;
+    [nodoc, deprecated="Use |level| to set input gain."] double? gain;
  
     // <p>
     //   The audio device's desired sound level. Defaults to the device's
@@ -192,7 +189,7 @@ namespace audio {
                         optional EmptyCallback callback);
 
     // Gets the information of all audio output and input devices.
-    [deprecated="Use $(ref:getDevices) instead."]
+    [nodoc, deprecated="Use $(ref:getDevices) instead."]
     static void getInfo(GetInfoCallback callback);
   };
 
@@ -210,7 +207,10 @@ namespace audio {
     // |devices|: List of all present audio devices after the change.
     static void onDeviceListChanged(AudioDeviceInfo[] devices);
 
-    // Fired when anything changes to the audio device configuration.
+    // <p>Fired when anything changes to the audio device configuration.</p>
+    // <p>Note that this event is kept around for backward-compatibility with
+    // apps that were white-listed to use audio API before Chrome 58. The
+    // event will not work for apps that are not part of that white-list.</p>

[Devlin, 2017/02/22 00:31:43]

Why this difference instead of the nodocs we have above?

[tbarzic, 2017/02/22 00:38:37]

Main reason is that there will be a clear error message when there is attempt to
use the methods - if the event is used it will fail silently (so it seemed
reasonable to document this).

[Devlin, 2017/02/22 14:13:14]

If this is only for whitelisted properties, can we just let them know?  It's
important that we don't brick them, but I don't know if we need to add public
documentation for them.  In-development APIs are meant to change. :)

[tbarzic, 2017/02/22 19:35:18]

OK, nodocing this.

     [deprecated="Use more granular $(ref:onLevelChanged),
                  $(ref:onMuteChanged) and $(ref:onDeviceListChanged) instead."]
     static void onDeviceChanged();