Remove docked windows entirely in M59.

chrome/common/extensions/api/windows.json

Index: chrome/common/extensions/api/windows.json
diff --git a/chrome/common/extensions/api/windows.json b/chrome/common/extensions/api/windows.json
index ed3f6013c7e49821b6a936c8f22ddffa46ec508f..99e97d87e61efd0f4777d7138029488598284044 100644
--- a/chrome/common/extensions/api/windows.json
+++ b/chrome/common/extensions/api/windows.json
@@ -20,7 +20,7 @@
         "id": "WindowState",
         "type": "string",
         "description": "The state of this browser window. Under some circumstances a Window may not be assigned state property, for example when querying closed windows from the $(ref:sessions) API.",
-        "enum": ["normal", "minimized", "maximized", "fullscreen", "docked"]

[Devlin, 2017/03/17 02:24:39]

I don't see anywhere in extension docs that we publicly mentioned that we were
deprecating docked windows, and we allow this as a possible state in
windows.create().  This means that any function that did windows.create({state:
'docked'}) will suddenly receive a runtime error and fail to function.  Did we
announce this somewhere that I missed?  If not, we may need to leave this for a
bit with a deprecated warning.

[varkha, 2017/03/17 03:39:44]

Would it not get silently converted to WINDOW_STATE_NONE here [1] and then
treated as ui::SHOW_STATE_DEFAULT here [2]?

[1] -
https://cs.chromium.org/chromium/src/out/Debug/gen/chrome/common/extensions/a...
[2] -
https://cs.chromium.org/chromium/src/chrome/browser/extensions/api/tabs/tabs_...

[Devlin, 2017/03/17 15:06:27]

No - the javascript bindings verify that the passed string is a valid option of
those specified in the "enum" list.  So trying to pass in "docked" would result
in an error (you can see the effect now by doing, e.g.
`chrome.windows.create({state: 'notastate'})`).

[afakhry, 2017/03/17 17:43:23]

Thanks Devlin for catching that!
I re-added the "docked" entry. But I have a couple of questions:
- Where do we update the documentation to mention docked windows will be
deprecated?
- Do we also need to revert the changes in files:
    window_manager_constants.mojom,
    tabs_api.cc
  in this CL?

[Devlin, 2017/03/17 19:27:00]

This file actually generates the public documentation.  Deprecating enums isn't
quite as graceful as other properties, unfortunately.  But something like this
should work:

"enum": [{
  "name": "normal",
  "description": <description>
}, {
  "name": "minimized",
  "description": <description>
}, {
  "name": "maximized",
  "description": <description>
}, {
  "name": "fullscreen",
  "description": <description>
}, {
  "name": "docked",
  "description": <i>Deprecated since Chrome M59.</i>  Docked windows are no
longer supported.  This state will be converted to \"normal\"."
}],

After that, you should be able to preview your changes with
src/ $ python chrome/common/extensions/docs/server2/preview.py
and visiting http://localhost:8000/extensions/windows#type-WindowState.

And you will need to revert the tabs_api.cc changes, since this file also
generates those windows:: enums. :)

Ideally, we can also probably add UMA to this to see how often "docked" is
passed in as a parameter, and use that data to determine if it is safe to remove
it entirely.

[afakhry, 2017/03/17 23:34:59]

Done. and done. Please take a look.

For the UMA part, I prefer to do this in a later CL.

+        "enum": ["normal", "minimized", "maximized", "fullscreen"]
       },
       {
         "id": "Window",