Improve ShouldAllowRequest comment

Expand comment to explain what happens with conflicting PolicyDecisions.

Bug: None
Change-Id: Id5c39ea0824cf1bf279644851addae3cc12e119a
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2164688
Commit-Queue: Mike Dougherty <michaeldo@chromium.org>
Reviewed-by: Eugene But <eugenebut@chromium.org>
Reviewed-by: Ali Juma <ajuma@chromium.org>
Cr-Commit-Position: refs/heads/master@{#762510}

ios/web/public/navigation/web_state_policy_decider.h

@@ -98,8 +98,14 @@ class WebStatePolicyDecider {
   virtual ~WebStatePolicyDecider();
 
   // Asks the decider whether the navigation corresponding to |request| should
-  // be allowed to continue. Defaults to true if not overriden.
+  // be allowed to continue. The first policy decider returning a PolicyDecision
+  // where ShouldCancelNavigation() is true will be the PolicyDecision used for
+  // the navigation. This means that a policy decider may not be called and have
+  // its expected decision performed for a given navigation. As such, the
+  // highest priority policy deciders should be added first to ensure those
+  // decisions are prioritized.
   // Called before WebStateObserver::DidStartNavigation.
+  // Defaults to PolicyDecision::Allow() if not overridden.
   // Never called in the following cases:
   //  - same-document back-forward and state change navigations
   virtual PolicyDecision ShouldAllowRequest(NSURLRequest* request,