Write docs for options_ui

extensions/common/api/extensions_manifest_types.json

Index: extensions/common/api/extensions_manifest_types.json
diff --git a/extensions/common/api/extensions_manifest_types.json b/extensions/common/api/extensions_manifest_types.json
index cff581c15404332395ea5c67d76d4caab8fde24d..99a30948b0e703313e03fae1f201e668e62bd82f 100644
--- a/extensions/common/api/extensions_manifest_types.json
+++ b/extensions/common/api/extensions_manifest_types.json
@@ -44,16 +44,16 @@
         "description": "The <code>options_ui</code> manifest property declares how the options page should be displayed.",
         "properties": {
           "page": {
-            "description": "The path to your options page.",
+            "description": "The path to your options page, relative to your extension's root.",
             "type": "string"
           },
           "chrome_style": {
-            "description": "If <code>true</code>, a Chrome user agent stylesheet will be applied to your options page. The default value is <code>false</code>.",
+            "description": "If <code>true</code>, a Chrome user agent stylesheet will be applied to your options page. The default value is <code>false</code>, but we recommend you enable it for a consistent UI with Chrome.",
             "optional": true,
             "type": "boolean"
           },
           "open_in_tab": {
-            "description": "If <code>true</code>, the options page will be opened in a new tab instead of in an embedded popup in chrome://extensions. The default value is <code>false</code>.",
+            "description": "<p>If <code>true</code>, your extension's options page will be opened in a new tab rather than embedded in <em>chrome://extensions</em>. The default is <code>false</code>, and we recommend that you don't change it.</p><p><strong>This is only useful to delay the inevitable deprecation of the old options UI!</strong> It will be removed soon, so try not to use it. It will break.</p>",
             "optional": true,
             "type": "boolean"
           }