Document that all-hosts works as an optional permission.

chrome/common/extensions/api/permissions.json

Index: chrome/common/extensions/api/permissions.json
diff --git a/chrome/common/extensions/api/permissions.json b/chrome/common/extensions/api/permissions.json
index 3ce74b43352e8ae48ef9225c180c021ff9ea842a..52a0c24ccec069c55fb6a0157d73a4936cd76370 100644
--- a/chrome/common/extensions/api/permissions.json
+++ b/chrome/common/extensions/api/permissions.json
@@ -15,13 +15,13 @@
             "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.

           }
         }
       }