[Security] Adding more extensive PHPDoc to UserInterface, AdvancedUserInterface and UserProviderInterface

1 files changed, 35 insertions, 2 deletions

diff --git a/Core/User/UserInterface.php b/Core/User/UserInterface.php
index 3b66956..7382cff 100644
--- a/Core/User/UserInterface.php
+++ b/Core/User/UserInterface.php
@@ -12,8 +12,20 @@
 namespace Symfony\Component\Security\Core\User;
 
 /**
- * UserInterface is the interface that user classes must implement.
+ * Represents the interface that all user classes must implement.
  *
+ * This interface is useful because the authentication layer can deal with
+ * the object through its lifecycle, using the object to get the encoded
+ * password (for checking against a submitted password), assigning roles
+ * and so on.
+ *
+ * Regardless of how your user are loaded or where they come from (a database,
+ * configuration, web service, etc), you will have a class that implements
+ * this interface. Objects that implement this interface are created and
+ * loaded by different objects that implement UserProviderInterface
+ *
+ * @see UserProviderInterface
+ * @see AdvancedUserInterface
  * @author Fabien Potencier <fabien@symfony.com>
  */
 interface UserInterface
@@ -21,6 +33,17 @@ interface UserInterface
     /**
      * Returns the roles granted to the user.
      *
+     * <code>
+     * public function getRoles()
+     * {
+     *     return array('ROLE_USER');
+     * }
+     * </code>
+     *
+     * Alternatively, the roles might be stored on a ``roles`` property,
+     * and populated in any number of different ways when the user object
+     * is created.
+     *
      * @return Role[] The user roles
      */
     function getRoles();
@@ -28,12 +51,17 @@ interface UserInterface
     /**
      * Returns the password used to authenticate the user.
      *
+     * This should be the encoded password. On authentication, a plain-text
+     * password will be salted, encoded, and then compared to this value.
+     *
      * @return string The password
      */
     function getPassword();
 
     /**
-     * Returns the salt.
+     * Returns the salt that was originally used to encode the password.
+     *
+     * This can return null if the password was not encoded using a salt.
      *
      * @return string The salt
      */
@@ -49,11 +77,16 @@ interface UserInterface
     /**
      * Removes sensitive data from the user.
      *
+     * This is important if, at any given point, sensitive information like
+     * the plain-text password is stored on this object.
+     *
      * @return void
      */
     function eraseCredentials();
 
     /**
+     * Returns whether or not the given user is equivalent to *this* user.
+     *
      * The equality comparison should neither be done by referential equality
      * nor by comparing identities (i.e. getId() === getId()).
      *