Improve ResourceRequestInfo::HasUserGesture API docs

content/public/browser/resource_request_info.h

Index: content/public/browser/resource_request_info.h
diff --git a/content/public/browser/resource_request_info.h b/content/public/browser/resource_request_info.h
index 6c86846547ec28c6c1aa714079676c1e3f21cbaa..00be9c7ceb9c6ad21123bd46ddc180f11bf6e11b 100644
--- a/content/public/browser/resource_request_info.h
+++ b/content/public/browser/resource_request_info.h
@@ -98,6 +98,13 @@ class ResourceRequestInfo {
 
   // True if the request was initiated by a user action (like a tap to follow
   // a link).
+  //
+  // Note that a false value does not mean the request was not initiated by a
+  // user gesture. Also note that the fact that a user gesture was active
+  // while the request was created does not imply that the user consciously
+  // wanted this request to happen nor is aware of it.
+  //
+  // DO NOT BASE SECURITY DECISIONS ON THIS FLAG!

[mkosiba (inactive), 2014/10/17 08:54:33]

Yes, you should be especially wary of using this to determine what to do with a
download :D

https://code.google.com/p/chromium/codesearch#chromium/src/chrome/browser/saf...

https://code.google.com/p/chromium/codesearch#chromium/src/content/browser/do...

[Randy Smith (Not in Mondays), 2014/10/20 14:20:46]

We'd welcome other other suggestions as to how to make download decisions (but
you'll probably have to mind-meld extensively with the current conditional
cascade and you may feel dirty afterwards :-}).  Whether and how to download
resources has a pretty strong tension between security and convenience, and when
we've moved towards security (e.g. prompting people around downloading PDFs
because they can contain arbitrary executable code) we've gotten howls of
protest.  I don't expect we're going to change our current use of user gesture,
even though we do indeed know it's not reliable :-{.

   virtual bool HasUserGesture() const = 0;
 
   // True if ResourceController::CancelAndIgnore() was called.  For example,