Documentation updates for chrome.tabCapture.

chrome/common/extensions/api/tab_capture.idl

Index: chrome/common/extensions/api/tab_capture.idl
diff --git a/chrome/common/extensions/api/tab_capture.idl b/chrome/common/extensions/api/tab_capture.idl
index 7e3e2a2567f560f3dcc4939ebe1eb080e538d149..e87e6291bba58f0a37785ff1b2ca40613cfdc970 100644
--- a/chrome/common/extensions/api/tab_capture.idl
+++ b/chrome/common/extensions/api/tab_capture.idl
@@ -47,12 +47,13 @@ namespace tabCapture {
   callback GetCapturedTabsCallback = void (CaptureInfo[] result);
 
   interface Functions {
-    // Captures the visible area of the currently active tab.
-    // This method can only be used on the currently active page after the
-    // extension has been <em>invoked</em>, similar to the way that
-    // <a href="activeTab.html">activeTab</a> works.
+    // Captures the visible area of the currently active tab.  This method can
+    // only be used on the currently active tab after the extension has been
+    // <em>invoked</em>, similar to the way that
+    // <a href="activeTab.html">activeTab</a> works.  Capture is maintained
+    // across page navigations within the tab, and stops when the tab is closed.

[miu, 2014/08/28 02:37:26]

s/when the tab is closed/when the tab is closed by the user, or the media stream
is closed by the extension/.

[not at google - send to devlin, 2014/08/28 02:44:31]

Are you sure it's maintained across page navigations? This isn't how activeTab
works.

[mark a. foltz, 2014/08/28 17:58:55]

Yes.  Removed reference to ActiveTab.

[mark a. foltz, 2014/08/28 17:58:55]

Done.

[not at google - send to devlin, 2014/08/28 18:21:54]

It seems to me from reading the code that tabCapture is lost as well on
navigation:

https://code.google.com/p/chromium/codesearch#chromium/src/chrome/browser/ext...

(it's enable for the tab by granting the tabCaptureForTab permission, line 57).

Fun thing: just above there (line 104) I have an experiment where we *do*
maintain these transient permissions for same-origin navigation.

     // |options| : Configures the returned media stream.
-    // |callback| : Callback with either the stream returned or null.
+    // |callback| : Callback with either the tab capture stream or |null|.

[not at google - send to devlin, 2014/08/28 02:44:31]

<code>null</code> looks better than |null| when rendered.

[mark a. foltz, 2014/08/28 17:58:55]

Done.

     static void capture(CaptureOptions options,
                         GetTabMediaCallback callback);
 
@@ -61,6 +62,7 @@ namespace tabCapture {
     // This allows extensions to inform the user that there is an existing
     // tab capture that would prevent a new tab capture from succeeding (or
     // to prevent redundant requests for the same tab).
+    // |callback| : Callback invoked with CaptureInfo[] for captured tabs.
     static void getCapturedTabs(GetCapturedTabsCallback callback);
   };
 
@@ -68,6 +70,7 @@ namespace tabCapture {
     // Event fired when the capture status of a tab changes.
     // This allows extension authors to keep track of the capture status of
     // tabs to keep UI elements like page actions and infobars in sync.
+    // |info| : CaptureInfo with new capture status for the tab.
     static void onStatusChanged(CaptureInfo info);
   };