docs: add/update doc comments

Author: kenjis

src/Auth.php

@@ -12,6 +12,8 @@
 use CodeIgniter\Shield\Models\UserModel;
 
 /**
+ * Facade for Authentication
+ *
  * @method Result    attempt(array $credentials)
  * @method Result    check(array $credentials)
  * @method bool      checkAction(string $token, string $type) [Session]
@@ -148,7 +150,7 @@ public function getProvider(): UserModel
 
     /**
      * Provide magic function-access to Authenticators to save use
-     * from repeating code here, and to allow them have their
+     * from repeating code here, and to allow them to have their
      * own, additional, features on top of the required ones,
      * like "remember-me" functionality.
      *

src/Authentication/Authentication.php

@@ -7,6 +7,9 @@
 use CodeIgniter\Shield\Config\Auth as AuthConfig;
 use CodeIgniter\Shield\Models\UserModel;
 
+/**
+ * Factory for Authenticators.
+ */
 class Authentication
 {
     /**
@@ -26,13 +29,10 @@ public function __construct(AuthConfig $config)
     }
 
     /**
-     * Returns an instance of the specified Authenticator.
+     * Creates and returns the shared instance of the specified Authenticator.
      *
-     * You can pass 'default' as the Authenticator and it
-     * will return an instance of the first Authenticator specified
-     * in the Auth config file.
-     *
-     * @param string|null $alias Authenticator alias
+     * @param string|null $alias Authenticator alias. Passing `null` returns the
+     *                           default authenticator.
      *
      * @throws AuthenticationException
      */
@@ -61,7 +61,7 @@ public function factory(?string $alias = null): AuthenticatorInterface
     }
 
     /**
-     * Sets the User provider to use
+     * Sets the User Provider to use.
      *
      * @return $this
      */

src/Helpers/auth_helper.php

@@ -22,8 +22,7 @@ function auth(?string $alias = null): Auth
 
 if (! function_exists('user_id')) {
     /**
-     * Returns the ID for the current logged in user.
-     * Note: For \CodeIgniter\Shield\Entities\User this will always return an int.
+     * Returns the ID for the current logged-in user.
      *
      * @return int|string|null
      */