Make the AccessResult API even clearer

+++ b/core/lib/Drupal/Core/Access/AccessResultInterface.php
@@ -31,11 +34,10 @@ public function isAllowed();
+   * @internal
    */
   public function isForbidden();

This is not true. Some access control logic may choose to return early if an intermediary result already is forbidden. That is a valid optimization strategy. If the logic whose execution can be avoided is very expensive (for example involving network I/O), that also is not premature optimization.

+++ b/core/lib/Drupal/Core/Access/AccessResultForbidden.php
@@ -4,6 +4,10 @@
+ * This is a kill switch — both orIf() and andIf() will result in
+ * isForbidden() if either results are isForbidden() and as such when checking
+ * for access with isAllowed() the end result will be FALSE.

'This' referred to the isForbidden() method in the paragraph that is being removed in this patch. If we're moving this paragraph to the AccessResultForbidden class, then 'this' no longer means the same thing.

Also, this sentence is too long and hard to understand.

The documentation changes to AccessResultInterface in #5 makes sense to me. Not sure what more to test for that.

This looks good. I added an extra 's' on 'return' (i.e. just because this returns FALSE) on commit.