Document that all-hosts works as an optional permission.

chrome/common/extensions/api/permissions.json

 // Copyright (c) 2012 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.
 
 [
   {
     "namespace": "permissions",
     "description": "Use the <code>chrome.permissions</code> API to request <a href=\"#manifest\">declared optional permissions</a> at run time rather than install time, so users understand why the permissions are needed and grant only those that are necessary.",
     "types": [
       {
         "id": "Permissions",
         "type": "object",
         "properties": {
           "permissions": {
             "type": "array",
             "items": {"type": "string"},
             "optional": true,
-            "description": "List of named permissions (does not include hosts or origins)."
+            "description": "List of named permissions (does not include hosts or origins).  Anything listed here must appear in the <code>optional_permissions</code> list in the manifest."
           },
           "origins": {
             "type": "array",
             "items": {"type": "string"},
             "optional": true,
-            "description": "List of origin permissions."
+            "description": "List of origin permissions. Anything listed here must be a subset of a host that appears in the <code>optional_permissions</code> list in the manifest. e.g. if <code>http://*.example.com/</code> or <code>http://*/</code> appears in <code>optional_permissions</code>, you can request an origin of <code>http://help.example.com/</code>. Any path is ignored."

[not at google - send to devlin, 2013/12/19 20:53:13]

nit: For example not e.g.
not nit: double-check that you don't need the trailing * in the URL pattern.

[Jeffrey Yasskin, 2013/12/19 21:32:50]

Done.
Checked. The / is required, but anything after it gets replaced with a *. We
actually should require an empty path, since it's an origin, not a URL, but we
can't do that within manifest v2.

[not at google - send to devlin, 2013/12/19 21:54:54]

The API is badly named, it's not an origin (as you say). More like an origin
pattern, but doesn't accept valid origins.

           }
         }
       }
     ],
     "events": [
       {
         "name": "onAdded",
         "type": "function",
         "description": "Fired when the extension acquires new permissions.",
         "parameters": [
@@ skipping 100 matching lines @@
                 "type": "boolean",
                 "description": "True if the permissions were removed."
               }
             ]
           }
         ]
       }
     ]
   }
 ]