Merge pull request #60783 from nextcloud/jtr/docs-PwConfirmationRequired

docs(appframework): clarify PasswordConfirmationRequired behavior in docblocks

Author: Altahrim

lib/public/AppFramework/Http/Attribute/PasswordConfirmationRequired.php

@@ -12,14 +12,26 @@
 use Attribute;
 
 /**
- * Attribute for controller methods that require the password to be confirmed with in the last 30 minutes
+ * Attribute for controller methods that require password confirmation, if
+ * supported by the active authentication backend.
+ *
+ * The exact enforcement behavior depends on the password confirmation
+ * middleware.
+ *
+ * In non-strict mode, this normally relies on a recent prior confirmation,
+ * currently defined by the middleware as within the last 30 minutes.
+ *
+ * In strict mode, confirmation is attempted as part of the current request.
+ * Credentials must be provided via Basic HTTP authentication.
  *
  * @since 27.0.0
  */
 #[Attribute]
 class PasswordConfirmationRequired {
 	/**
-	 * @param bool $strict - Whether password confirmation needs to happen in the request.
+	 * @param bool $strict Whether password confirmation must happen as part of
+	 *                     the current request instead of relying on a recent
+	 *                     prior confirmation.
 	 *
 	 * @since 31.0.0
 	 */
@@ -29,10 +41,11 @@ public function __construct(
 	}
 
 	/**
+	 * Returns whether password confirmation must happen during the current request.
+	 *
 	 * @since 31.0.0
 	 */
 	public function getStrict(): bool {
 		return $this->strict;
 	}
-
 }