[SafeBrowsing] Clarify `danger_level` in safe_browsing/README.md

chrome/browser/resources/safe_browsing/README.md

 # Behavior of Download File Types in Chrome
 
 This describes how to adjust file-type download behavior in
 Chrome including interactions with Safe Browsing. The metadata described
 here, and stored in `download_file_types.asciipb`, will be both baked into
 Chrome released and pushable to Chrome between releases (via
 `FileTypePolicies` class).  http://crbug.com/596555
 
 Rendered version of this file: https://chromium.googlesource.com/chromium/src/+/master/chrome/browser/resources/safe_browsing/README.md
 
@@ skipping 47 matching lines @@
      as follows before writing out the binary proto.
 
        1. If there's an entry matching the built platform,
          that will be preferred. Otherwise,
 
        2. If there's a "PLATFORM_ANY" (i.e. `platform` is not set),
        that will be used. Otherwise,
 
        3. The `default_file_type`'s settings will be filled in.
 
-  * `platform_settings.danger_level`: (required)
+  * `platform_settings.danger_level`: (required) Controls how files should be
+    handled by the UI in the absence of a better signal from the Safe Browsing
+    ping. This applies to all file types where `ping_setting` is either
+    `SAMPLED_PING` or `NO_PING`, and downloads where the Safe Browsing ping
+    either fails, is disabled, or returns an `UNKNOWN` verdict. Exceptions are
+    noted below.
+
+    The warning controlled here is a generic "This file may harm your computer."
+    If the Safe Browsing verdict is `UNKNOWN` or `DANGEROUS`, Chrome will show

[Nathan Parker, 2016/06/21 16:55:00]

s/UNKNOWN/UNCOMMON, POTENTIALLY_UNWANTED, DANGEROUS_HOST/

[asanka, 2016/06/21 16:58:48]

D'oh. Done.

+    that more severe warning regardless of this setting.
+
     * `NOT_DANGEROUS`: Safe to download and open, even if the download
-       was accidental.
+       was accidental. No additional warnings are necessary.
     * `DANGEROUS`: Always warn the user that this file may harm their
       computer. We let them continue or discard the file. If Safe
-      Browsing returns a SAFE verdict, we still warn the user.
-    * `ALLOW_ON_USER_GESTURE`: Warn the user normally but skip the warning
-      if there was a user gesture or the user visited this site before
-      midnight last night (i.e. is a repeat visit). If Safe Browsing
-      returns a SAFE verdict for this file, it won't show a warning.
+      Browsing returns a `SAFE` verdict, we still warn the user.
+    * `ALLOW_ON_USER_GESTURE`: Potentially dangerous, but is likely harmless if
+      the user is familiar with host and if the download was intentional. Chrome
+      doesn't warn the user if both of the following conditions are true:
+
+        * There is a user gesture associated with the network request that
+          initiated the download.
+        * There is a recorded visit to the referring origin that's older than
+          the most recent midnight. This is taken to imply that the user has a
+          history of visiting the site.
+
+      In addition, Chrome skips the warning if the download was explicit (i.e.
+      the user selected "Save link as ..." from the context menu), or if the
+      navigation that resulted in the download was initiated using the Omnibox.
 
   * `platform_settings.auto_open_hint`: (required).
     * `ALLOW_AUTO_OPEN`: File type can be opened automatically if the user
       selected that option from the download tray on a previous download
       of this type.
     * `DISALLOW_AUTO_OPEN`:  Never let the file automatically open.
       Files that should be disallowed from auto-opening include those that
       execute arbitrary or harmful code with user privileges, or change
       configuration of the system to cause harmful behavior immediately
       or at some time in the future. We *do* allow auto-open for files
@@ skipping 19 matching lines @@
     users' downloads with unknown extensions (or
     ping_setting=SAMPLED_PING) should we send light-pings? [0.0 .. 1.0]
 
   * `file_types`: The big list of all known file types. Keep them
      sorted by extension.
 
   * `default_file_type`: Settings used if a downloaded file is not in
     the above list. `extension` is ignored, but other settings are used.
     The ping_setting should be SAMPLED_PING for all platforms.