[DNR] Finish documentation for the feedback API

This CL adds documentation for the feedback API as well as the
declarativeNetRequestFeedback permission.

The getMatchedRules has also been made available for beta.

Bug: 1044702
Change-Id: I9752110fce82b56efe5666fc811c018b1cf2e895
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2032415Reviewed-by: Karan Bhatia <karandeepb@chromium.org>
Commit-Queue: Kelvin Jiang <kelvinjiang@chromium.org>
Cr-Commit-Position: refs/heads/master@{#737853}

chrome/common/extensions/docs/templates/intros/declarativeNetRequest.html

@@ -2,7 +2,9 @@
 
 <p>
 You must declare the <code>"declarativeNetRequest"</code> permission in the
-extension <a href="manifest">manifest</a> to use this API.
+extension <a href="manifest">manifest</a> to use this API. The
+<code>"declarativeNetRequestFeedback"</code> permission is required to access
+functions and events which return information on declarative rules matched.
 <a href="declare_permissions">Host permissions</a> are required if the extension
 wants to redirect requests. You must also declare the
 <code>"declarative_net_request"</code> manifest key, which should be a
@@ -21,6 +23,7 @@ declarative rules to use, as shown below.
   },
   "permissions": [
     "declarativeNetRequest",
+    "declarativeNetRequestFeedback",
     "*://example.com/*"
   ],</b>
   ...

chrome/common/extensions/docs/templates/json/intro_tables.json

@@ -86,12 +86,7 @@
   "declarativeNetRequest": {
     "Permissions": [
       {
-        "class": "code",
-        "text": "\"declarativeNetRequest\""
-      },
-      {
-        "link": "declare_permissions#host-permissions",
-        "text": "host permissions"
+        "partial": "intro_tables/declarative_net_request_permissions.html"
       }
     ]
   },

chrome/common/extensions/docs/templates/json/permissions.json

@@ -30,6 +30,9 @@
   "clipboardWrite": {
     "partial": "permissions/clipboard_write.html"
   },
+  "declarativeNetRequestFeedback": {
+    "partial": "permissions/declarative_net_request_feedback.html"
+  },
   "experimental": {
     "partial": "permissions/experimental.html"
   },

chrome/common/extensions/docs/templates/private/intro_tables/declarative_net_request_permissions.html

+<code><q>declarativeNetRequest</q></code>
+<br><code><q>declarativeNetRequestFeedback</q></code>
+<br><a href="declare_permissions#host-permissions">host permissions</a>
+<br><br>Note that <code>declarativeNetRequestFeedback</code> and host permissions should only be specified when necessary.
\ No newline at end of file

chrome/common/extensions/docs/templates/private/permissions/declarative_net_request_feedback.html

+Grants the extension access to events and methods within the <a href="declarativeNetRequest">chrome.declarativeNetRequest</a> API which return information on declarative rules matched.
\ No newline at end of file

extensions/common/api/_api_features.json

@@ -144,11 +144,6 @@
     "dependencies": ["permission:declarativeNetRequest"],
     "contexts": ["blessed_extension"]
   },
-  "declarativeNetRequest.getMatchedRules": {
-    "dependencies": ["permission:declarativeNetRequest"],
-    "contexts": ["blessed_extension"],
-    "channel": "trunk"
-  },
   "declarativeNetRequest.onRuleMatchedDebug": {
     "dependencies": ["permission:declarativeNetRequest", "permission:declarativeNetRequestFeedback"],
     "contexts": ["blessed_extension"],

extensions/common/api/_permission_features.json

@@ -212,7 +212,7 @@
     "min_manifest_version": 2
   },
   "declarativeNetRequestFeedback": {
-    "channel": "trunk",
+    "channel": "beta",
     "extension_types": ["extension"],
     "min_manifest_version": 2
   },

extensions/common/api/declarative_net_request.idl

@@ -245,7 +245,6 @@ namespace declarativeNetRequest {
     SourceType sourceType;
   };
 
-  [nodoc]
   dictionary MatchedRuleInfo {
     MatchedRule rule;
 
@@ -259,7 +258,6 @@ namespace declarativeNetRequest {
     long tabId;
   };
 
-  [nodoc]
   dictionary MatchedRulesFilter {
     // If specified, only matches rules for the given tab.
     long? tabId;
@@ -268,7 +266,6 @@ namespace declarativeNetRequest {
     double? minTimeStamp;
   };
 
-  [nodoc]
   dictionary RulesMatchedDetails {
      // Rules matching the given filter.
      MatchedRuleInfo[] rulesMatchedInfo;
@@ -350,9 +347,19 @@ namespace declarativeNetRequest {
     // raised in case of transient internal errors.
     static void getDynamicRules(GetRulesCallback callback);
 
-    // TODO(crbug.com/1044702): Add documentation once implementation is
-    // complete.
-    [nodoc]
+    // Returns all rules matched for the extension. Callers can optionally
+    // filter the list of matched rules by specifying a |filter|. This method is
+    // only available to extensions with the
+    // <code>declarativeNetRequestFeedback</code> permission or having the
+    // <code>activeTab</code> permission granted for the <code>tabId</code>
+    // specified in <code>filter</code>.
+    // Note: Rules not associated with an active document that were matched more
+    // than five minutes ago will not be returned.
+    // |filter|: An object to filter the list of matched rules.
+    // |callback|: Called once the list of matched rules has been fetched. In
+    // case of an error, $(ref:runtime.lastError) will be set to denote the
+    // error and no rules will be returned. This can happen for multiple
+    // reasons, such as insufficient permissions, or exceeding the quota.
     static void getMatchedRules(optional MatchedRulesFilter filter,
         GetMatchedRulesCallback callback);
 
@@ -374,16 +381,17 @@ namespace declarativeNetRequest {
     // Time interval within which <code>MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL
     // getMatchedRules</code> calls can be made, specified in minutes.
     // Additional calls will fail immediately and set $(ref:runtime.lastError).
-    [value=10, nodoc] static long GETMATCHEDRULES_QUOTA_INTERVAL();
+    [value=10] static long GETMATCHEDRULES_QUOTA_INTERVAL();
 
     // The number of times <code>getMatchedRules</code> can be called within a
     // period of <code>GETMATCHEDRULES_QUOTA_INTERVAL</code>.
-    [value=20, nodoc] static long MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL();
+    [value=20] static long MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL();
   };
 
   interface Events {
     // Fired when a rule is matched with a request. Only available for unpacked
-    // extensions as this is intended to be used for debugging purposes only.
+    // extensions with the <code>declarativeNetRequestFeedback</code> permission
+    // as this is intended to be used for debugging purposes only.
     // |matched_rule_info|: The rule that has been matched along with
     // information about the associated request.
     static void onRuleMatchedDebug(MatchedRuleInfoDebug matched_rule_info);