From 4cab48c0fdfa8118eeab547dbff1255e9aceb4eb Mon Sep 17 00:00:00 2001
From: Franz Liedke <franz@develophp.org>
Date: Tue, 20 Aug 2019 17:18:18 +0200
Subject: [PATCH] Document permission check methods

---
 src/User/AssertPermissionTrait.php | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/src/User/AssertPermissionTrait.php b/src/User/AssertPermissionTrait.php
index b58139ab4..5ab3679d8 100644
--- a/src/User/AssertPermissionTrait.php
+++ b/src/User/AssertPermissionTrait.php
@@ -15,6 +15,13 @@ use Flarum\User\Exception\PermissionDeniedException;
 trait AssertPermissionTrait
 {
     /**
+     * Ensure the current user is allowed to do something.
+     *
+     * If the condition is not met, an exception will be thrown that signals the
+     * lack of permissions. This is about *authorization*, i.e. retrying such a
+     * request / operation without a change in permissions (or using another
+     * user account) is pointless.
+     *
      * @param bool $condition
      * @throws PermissionDeniedException
      */
@@ -26,6 +33,12 @@ trait AssertPermissionTrait
     }
 
     /**
+     * Ensure the current user is authenticated.
+     *
+     * This will throw an exception for guest users, signaling that
+     * *authorization* failed. Thus, they could retry the operation after
+     * logging in (or using other means of authentication).
+     *
      * @param bool $condition
      * @throws NotAuthenticatedException
      */