improved PHPDoc descriptions

Author: dg

src/Security/Authorizator.php

@@ -9,8 +9,7 @@
 
 
 /**
- * Authorizator checks if a given role has authorization
- * to access a given resource.
+ * Checks whether a given role has access to a given resource.
  */
 interface Authorizator
 {

src/Security/Identity.php

@@ -72,7 +72,7 @@ public function getRoles(): array
 
 
 	/**
-	 * Returns a user data.
+	 * Returns user data.
 	 */
 	public function getData(): array
 	{

src/Security/IdentityHandler.php

@@ -9,11 +9,17 @@
 
 
 /**
- * Adjusts identity from/to storage.
+ * Serializes and restores identity to/from persistent storage.
  */
 interface IdentityHandler
 {
+	/**
+	 * Called before identity is written to storage. Typically replaces the full identity with a lightweight token.
+	 */
 	function sleepIdentity(IIdentity $identity): IIdentity;
 
+	/**
+	 * Called after identity is read from storage. Typically refreshes roles or validates the token. Returns null to force logout.
+	 */
 	function wakeupIdentity(IIdentity $identity): ?IIdentity;
 }

src/Security/Passwords.php

@@ -12,12 +12,12 @@
 
 
 /**
- * Password Hashing.
+ * Password hashing and verification.
  */
 class Passwords
 {
 	/**
-	 * Chooses which secure algorithm is used for hashing and how to configure it.
+	 * Configures the hashing algorithm and its options.
 	 * @see https://php.net/manual/en/password.constants.php
 	 */
 	public function __construct(
@@ -28,7 +28,7 @@ public function __construct(
 
 
 	/**
-	 * Computes password´s hash. The result contains the algorithm ID and its settings, cryptographical salt and the hash itself.
+	 * Computes a password hash containing the algorithm ID, settings, salt, and the hash itself.
 	 */
 	public function hash(
 		#[\SensitiveParameter]
@@ -49,7 +49,7 @@ public function hash(
 
 
 	/**
-	 * Finds out, whether the given password matches the given hash.
+	 * Checks whether the password matches the given hash.
 	 */
 	public function verify(
 		#[\SensitiveParameter]
@@ -62,7 +62,7 @@ public function verify(
 
 
 	/**
-	 * Finds out if the hash matches the options given in constructor.
+	 * Checks whether the hash needs to be rehashed with the current algorithm and options.
 	 */
 	public function needsRehash(string $hash): bool
 	{

src/Security/Permission.php

@@ -80,7 +80,7 @@ public function addRole(string $role, string|array|null $parents = null): static
 
 
 	/**
-	 * Returns true if the Role exists in the list.
+	 * Checks whether the Role exists in the list.
 	 */
 	public function hasRole(string $role): bool
 	{
@@ -213,7 +213,7 @@ public function removeAllRoles(): static
 
 
 	/**
-	 * Adds a Resource having an identifier unique to the list.
+	 * Adds a Resource to the list.
 	 *
 	 * @throws Nette\InvalidArgumentException
 	 * @throws Nette\InvalidStateException
@@ -241,7 +241,7 @@ public function addResource(string $resource, ?string $parent = null): static
 
 
 	/**
-	 * Returns true if the Resource exists in the list.
+	 * Checks whether the Resource exists in the list.
 	 */
 	public function hasResource(string $resource): bool
 	{
@@ -603,7 +603,7 @@ public function isAllowed(
 
 
 	/**
-	 * Returns real currently queried Role. Use by assertion.
+	 * Returns the role currently being queried. Used by assertion callbacks.
 	 */
 	public function getQueriedRole(): string|Role|null
 	{
@@ -612,7 +612,7 @@ public function getQueriedRole(): string|Role|null
 
 
 	/**
-	 * Returns real currently queried Resource. Use by assertion.
+	 * Returns the resource currently being queried. Used by assertion callbacks.
 	 */
 	public function getQueriedResource(): string|Resource|null
 	{

src/Security/Resource.php

@@ -9,7 +9,7 @@
 
 
 /**
- * Represents resource, an object to which access is controlled.
+ * Represents a resource to which access is controlled.
  */
 interface Resource
 {

src/Security/Role.php

@@ -9,7 +9,7 @@
 
 
 /**
- * Represents role, an object that may request access to an IResource.
+ * Represents a role that can be granted access to resources.
  */
 interface Role
 {

src/Security/SimpleAuthenticator.php

@@ -28,8 +28,7 @@ public function __construct(
 
 
 	/**
-	 * Performs an authentication against e.g. database.
-	 * and returns IIdentity on success or throws AuthenticationException
+	 * Authenticates against the in-memory list of users (case-insensitive username).
 	 * @throws AuthenticationException
 	 */
 	public function authenticate(

src/Security/User.php

@@ -79,8 +79,8 @@ final public function getStorage(): UserStorage
 
 
 	/**
-	 * Conducts the authentication process. Parameters are optional.
-	 * @param  string|IIdentity  $username  name or Identity
+	 * Authenticates the user. Accepts username and password, or an IIdentity directly.
+	 * @param  string|IIdentity  $username  username or identity
 	 * @throws AuthenticationException if authentication was not successful
 	 */
 	public function login(
@@ -128,7 +128,7 @@ final public function logout(bool $clearIdentity = false): void
 
 
 	/**
-	 * Is this user authenticated?
+	 * Checks whether the user is authenticated.
 	 */
 	final public function isLoggedIn(): bool
 	{
@@ -141,7 +141,7 @@ final public function isLoggedIn(): bool
 
 
 	/**
-	 * Returns current user identity, if any.
+	 * Returns the current user identity, or null if not authenticated.
 	 */
 	final public function getIdentity(): ?IIdentity
 	{
@@ -178,6 +178,9 @@ public function getId(): string|int|null
 	}
 
 
+	/**
+	 * Discards cached authentication state, forcing a reload from storage on next access.
+	 */
 	final public function refreshStorage(): void
 	{
 		$this->identity = $this->authenticated = $this->logoutReason = null;
@@ -208,7 +211,7 @@ final public function getAuthenticator(): IAuthenticator
 
 
 	/**
-	 * Returns authentication handler.
+	 * Returns authentication handler, or null if none is set.
 	 */
 	final public function getAuthenticatorIfExists(): ?IAuthenticator
 	{
@@ -234,7 +237,7 @@ public function setExpiration(?string $expire, bool $clearIdentity = false): sta
 
 
 	/**
-	 * Why was user logged out? Returns LOGOUT_MANUAL or LOGOUT_INACTIVITY.
+	 * Returns the logout reason: LogoutManual or LogoutInactivity, or null if not applicable.
 	 */
 	final public function getLogoutReason(): ?int
 	{
@@ -246,7 +249,7 @@ final public function getLogoutReason(): ?int
 
 
 	/**
-	 * Returns a list of effective roles that a user has been granted.
+	 * Returns effective roles of the user. Unauthenticated users get the guest role.
 	 */
 	public function getRoles(): array
 	{
@@ -260,7 +263,7 @@ public function getRoles(): array
 
 
 	/**
-	 * Is a user in the specified effective role?
+	 * Checks whether the user has the specified effective role.
 	 */
 	final public function isInRole(string $role): bool
 	{
@@ -275,8 +278,8 @@ final public function isInRole(string $role): bool
 
 
 	/**
-	 * Has a user effective access to the Resource?
-	 * If $resource is null, then the query applies to all resources.
+	 * Checks whether the user has access to the given resource and privilege.
+	 * Null means all resources or all privileges.
 	 */
 	public function isAllowed(mixed $resource = Authorizator::All, mixed $privilege = Authorizator::All): bool
 	{
@@ -314,7 +317,7 @@ final public function getAuthorizator(): Authorizator
 
 
 	/**
-	 * Returns current authorization handler.
+	 * Returns authorization handler, or null if none is set.
 	 */
 	final public function getAuthorizatorIfExists(): ?Authorizator
 	{

src/Security/UserStorage.php

@@ -9,7 +9,7 @@
 
 
 /**
- * Interface for persistent storage for user object data.
+ * Persistent storage for user authentication state and identity.
  */
 interface UserStorage
 {
@@ -20,12 +20,12 @@ interface UserStorage
 	public const LOGOUT_INACTIVITY = 2;
 
 	/**
-	 * Sets the authenticated state of user.
+	 * Saves authenticated identity to storage.
 	 */
 	function saveAuthentication(IIdentity $identity): void;
 
 	/**
-	 * Removed authenticated state of user.
+	 * Removes authenticated state from storage.
 	 */
 	function clearAuthentication(bool $clearIdentity): void;