merged branch hhamon/username_password_token_doc (PR #4172)

Commits
-------

9ac8d43 [Security] fixed phpdoc.
a3ecea3 [Security] added some missing phpdoc for AbstractToken::setUser() and UsernamePasswordToken::__construct() methods.

Discussion
----------

Fixes PHPDoc in UsernamePasswordToken and AbstractToken classes

Bug fix: no
Feature addition: no
Backwards compatibility break: no
Symfony2 tests pass: yes
Fixes the following tickets: -
Todo: -

src/Symfony/Component/Security/Core/Authentication/Token/AbstractToken.php

@@ -75,6 +75,15 @@ public function getUser()
         return $this->user;
     }
 
+    /**
+     * Sets the user in the token.
+     *
+     * The user can be a UserInterface instance, or an object implementing
+     * a __toString method or the username as a regular string.
+     *
+     * @param mixed $user The user
+     * @throws \InvalidArgumentException
+     */
     public function setUser($user)
     {
         if (!($user instanceof UserInterface || (is_object($user) && method_exists($user, '__toString')) || is_string($user))) {

src/Symfony/Component/Security/Core/Authentication/Token/UsernamePasswordToken.php

@@ -24,7 +24,7 @@ class UsernamePasswordToken extends AbstractToken
     /**
      * Constructor.
      *
-     * @param string $user        The username (like a nickname, email address, etc.)
+     * @param string $user        The username (like a nickname, email address, etc.), or a UserInterface instance or an object implementing a __toString method.
      * @param string $credentials This usually is the password of the user
      * @param string $providerKey The provider key
      * @param array  $roles       An array of roles