Strawman proposal for chrome.experimental.clear.*

chrome/common/extensions/api/extension_api.json

 [
   {
     "namespace": "extension",
     "unprivileged": true,
     "types": [
       {
         "id": "MessageSender",
         "type": "object",
         "description": "An object containing information about the script context that sent a message or request.",
         "properties": {
@@ skipping 8072 matching lines @@
                 "name": "result",
                 "type": "string",
                 "description": "A string result code. The value is non-empty on success only in tests.",
                 "optional": "true"
               }
             ]
           }
         ]
       }
     ]
+  },
+  {
+    "namespace": "experimental.clear",

[kathyw, 2011/08/25 18:33:15]

It's a little odd to have a namespace that is a verb. Usually method names are
verbs, and namespaces are nouns.

Maybe rename to experimental.browserData?

(I'm guessing you want to say "clear" to make clear -- haha -- that you can only
delete data, not read or manipulate it. But it's just a weird precedent to set.
Also, "clear" has many meanings and is easy to read as a noun, so it might be
nice to use a different word as the primary verb.)

+    "types": [
+      {
+        "id": "TimePeriod",
+        "type": "string",
+        "enum": ["last_hour", "last_day", "last_week", "last_month", "everything"],
+        "description": "The timeframe inside of which to delete browsing data. Passing 'last_day', for example, will delete all browsing data that was touched between 24 hours ago and right now, inclusive."

[kathyw, 2011/08/25 18:33:15]

will delete -> deletes

+      }
+    ],
+    "functions": [
+      {
+        "name": "browsingData",

[kathyw, 2011/08/25 18:33:15]

browsingData -> clear

or maybe "remove"

or maybe "delete"

+        "description": "Clears data generated by browsing within a particular timeframe.",

[kathyw, 2011/08/25 18:33:15]

data generated by -> the specified kinds of data that was the result of
within -> during

+        "type": "function",
+        "parameters": [
+          {
+            "$ref": "TimePeriod",
+            "name": "period"
+          },
+          {
+            "name": "dataToRemove",
+            "type": "object",
+            "description": "An object whose properties specify which browsing data types ought to be cleared. You may set as many or as few as you like in a single call, each is optional (defaulting to <code>false</code>).",

[kathyw, 2011/08/25 18:33:15]

First sentence could be more straightforward:
 -> An object specifying which browsing data types to clear.
may -> can
few -> few properties
, each is -> ; each property is (or ". Each property is")

Finally, the default value seems as important as the fact that the value is
optional, so I wouldn't use parentheses. Something like:

optional (...) -> optional and has a default value of <code>false</code>

+            "properties": {
+              "cache": {

[kathyw, 2011/08/25 18:33:15]

cache -> clearCache

+                "type": "boolean",
+                "optional": true,
+                "description": "Should the browser cache be cleared?"

[kathyw, 2011/08/25 18:33:15]

Interesting construction, having these as questions. I'd say the mapping from
true/false to yes/no isn't perfect, though. Also, you could see these as
philsophical questions with a long-term effect, rather than immediate actions. I
guess I'd use a more usual construction, such as:

Specify <code>true</code> to remove data from the browser cache.

+              },
+              "cookies": {
+                "type": "boolean",
+                "optional": true,
+                "description": "Should the browser's cookies be cleared?"

[kathyw, 2011/08/25 18:33:15]

Specify <code>true</code> to remove browser cookies.

+              },
+              "downloads": {
+                "type": "boolean",
+                "optional": true,
+                "description": "Should the browser's download list be cleared?"
+              },
+              "formData": {
+                "type": "boolean",
+                "optional": true,
+                "description": "Should stored form data be cleared?"
+              },
+              "history": {
+                "type": "boolean",
+                "optional": true,
+                "description": "Should the browser's history be cleared?"
+              },
+              "passwords": {
+                "type": "boolean",
+                "optional": true,
+                "description": "Should the stored passwords be cleared?"
+              }
+            }
+          },
+          {
+            "name": "callback",
+            "type": "function",
+            "description": "Called when deletion has completed.",
+            "optional": true,
+            "parameters": []
+          }
+        ]
+      },
+      {
+        "name": "cache",
+        "description": "Clears the browser's cache.",
+        "type": "function",
+        "parameters": [
+          {
+            "$ref": "TimePeriod",
+            "name": "period"
+          },
+          {
+            "name": "callback",
+            "type": "function",
+            "description": "Called when the browser's cache has cleared.",
+            "optional": true,
+            "parameters": []
+          }
+        ]
+      },
+      {
+        "name": "cookies",
+        "description": "Clears the browser's cookies and site data.",
+        "type": "function",
+        "parameters": [
+          {
+            "$ref": "TimePeriod",
+            "name": "period"
+          },
+          {
+            "name": "callback",
+            "type": "function",
+            "description": "Called when the browser's cookies and site data have been cleared.",
+            "optional": true,
+            "parameters": []
+          }
+        ]
+      },
+      {
+        "name": "downloads",
+        "description": "Clears the browser's list of downloaded files (<em>not</em> the downloaded files themselves).",
+        "type": "function",
+        "parameters": [
+          {
+            "$ref": "TimePeriod",
+            "name": "period"
+          },
+          {
+            "name": "callback",
+            "type": "function",
+            "description": "Called when the browser's list of downloaded files has been cleared.",
+            "optional": true,
+            "parameters": []
+          }
+        ]
+      },
+      {
+        "name": "formData",
+        "description": "Clears the browser's stored form data (autofill).",
+        "type": "function",
+        "parameters": [
+          {
+            "$ref": "TimePeriod",
+            "name": "period"
+          },
+          {
+            "name": "callback",
+            "type": "function",
+            "description": "Called when the browser's form data has been cleared.",
+            "optional": true,
+            "parameters": []
+          }
+        ]
+      },
+      {
+        "name": "history",
+        "description": "Clears the browser's history.",
+        "type": "function",
+        "parameters": [
+          {
+            "$ref": "TimePeriod",
+            "name": "period"
+          },
+          {
+            "name": "callback",
+            "type": "function",
+            "description": "Called when the browser's history has cleared.",
+            "optional": true,
+            "parameters": []
+          }
+        ]
+      },
+      {
+        "name": "passwords",
+        "description": "Clears the browser's stored passwords.",
+        "type": "function",
+        "parameters": [
+          {
+            "$ref": "TimePeriod",
+            "name": "period"
+          },
+          {
+            "name": "callback",
+            "type": "function",
+            "description": "Called when the browser's passwords have been cleared.",
+            "optional": true,
+            "parameters": []
+          }
+        ]
+      }
+    ]
   }
 ]