Document fullscreen/ESC behaviour.

And the fact that the user can leave fullscreen by pressing ESC but this
can be prevented by the developer by cancelling the event and requesting
a special permission.

BUG=320487

Review URL: https://codereview.chromium.org/116083008

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@243087 0039d316-1c4b-4281-b951-d872f2087c98

chrome/common/extensions/api/app_window.idl

@@ -135,7 +135,13 @@ namespace app.window {
     // Focus the window.
     static void focus();
 
-    // Fullscreens the window.
+    // Fullscreens the window.<br>
+    // The user will be able to restore the window by pressing ESC. An
+    // application can prevent the fullscreen state to be left when ESC is
+    // pressed by requesting the <b>overrideEscFullscreen</b> permission and
+    // canceling the event by calling .preventDefault(), like this:<br>
+    // <code>window.onKeyDown = function(e) { if (e.keyCode == 27 /* ESC */) {
+    // e.preventDefault(); } };</code>
     static void fullscreen();
 
     // Is the window fullscreen?