minor #10046 [2.3][Component/Security] Fixed some phpdocs in Security/Core (stloyd)

This PR was merged into the 2.3 branch.

Discussion
----------

[2.3][Component/Security] Fixed some phpdocs in Security/Core

| Q             | A
| ------------- | ---
| Bug fix?      | kinda*
| New feature?  | no
| License       | MIT

\* - those missing phpdocs lead to problems when debugging with IDE, as well as some were wrong (i.e. `SecurityContextInterface::isGranted()`) as parameters differ in interface & class implementing it

Commits
-------

80fae1d [Component/Security] Fixed some phpdocs in Security/Core

src/Symfony/Component/Security/Core/Authentication/Provider/RememberMeAuthenticationProvider.php

@@ -22,6 +22,13 @@ class RememberMeAuthenticationProvider implements AuthenticationProviderInterfac
     private $key;
     private $providerKey;
 
+    /**
+     * Constructor.
+     *
+     * @param UserCheckerInterface $userChecker An UserCheckerInterface interface
+     * @param string               $key         A key
+     * @param string               $providerKey A provider key
+     */
     public function __construct(UserCheckerInterface $userChecker, $key, $providerKey)
     {
         $this->userChecker = $userChecker;
@@ -29,6 +36,9 @@ class RememberMeAuthenticationProvider implements AuthenticationProviderInterfac
         $this->providerKey = $providerKey;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function authenticate(TokenInterface $token)
     {
         if (!$this->supports($token)) {
@@ -48,6 +58,9 @@ class RememberMeAuthenticationProvider implements AuthenticationProviderInterfac
         return $authenticatedToken;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function supports(TokenInterface $token)
     {
         return $token instanceof RememberMeToken && $token->getProviderKey() === $this->providerKey;

src/Symfony/Component/Security/Core/Authentication/RememberMe/InMemoryTokenProvider.php

@@ -22,6 +22,9 @@ class InMemoryTokenProvider implements TokenProviderInterface
 {
     private $tokens = array();
 
+    /**
+     * {@inheritdoc}
+     */
     public function loadTokenBySeries($series)
     {
         if (!isset($this->tokens[$series])) {
@@ -31,6 +34,9 @@ class InMemoryTokenProvider implements TokenProviderInterface
         return $this->tokens[$series];
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function updateToken($series, $tokenValue, \DateTime $lastUsed)
     {
         if (!isset($this->tokens[$series])) {
@@ -47,11 +53,17 @@ class InMemoryTokenProvider implements TokenProviderInterface
         $this->tokens[$series] = $token;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function deleteTokenBySeries($series)
     {
         unset($this->tokens[$series]);
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function createNewToken(PersistentTokenInterface $token)
     {
         $this->tokens[$token->getSeries()] = $token;

src/Symfony/Component/Security/Core/Authentication/RememberMe/PersistentToken.php

@@ -58,9 +58,7 @@ final class PersistentToken implements PersistentTokenInterface
     }
 
     /**
-     * Returns the class of the user
-     *
-     * @return string
+     * {@inheritdoc}
      */
     public function getClass()
     {
@@ -68,9 +66,7 @@ final class PersistentToken implements PersistentTokenInterface
     }
 
     /**
-     * Returns the username
-     *
-     * @return string
+     * {@inheritdoc}
      */
     public function getUsername()
     {
@@ -78,9 +74,7 @@ final class PersistentToken implements PersistentTokenInterface
     }
 
     /**
-     * Returns the series
-     *
-     * @return string
+     * {@inheritdoc}
      */
     public function getSeries()
     {
@@ -88,9 +82,7 @@ final class PersistentToken implements PersistentTokenInterface
     }
 
     /**
-     * Returns the token value
-     *
-     * @return string
+     * {@inheritdoc}
      */
     public function getTokenValue()
     {
@@ -98,9 +90,7 @@ final class PersistentToken implements PersistentTokenInterface
     }
 
     /**
-     * Returns the time the token was last used
-     *
-     * @return \DateTime
+     * {@inheritdoc}
      */
     public function getLastUsed()
     {

src/Symfony/Component/Security/Core/Authentication/RememberMe/PersistentTokenInterface.php

@@ -20,31 +20,36 @@ namespace Symfony\Component\Security\Core\Authentication\RememberMe;
 interface PersistentTokenInterface
 {
     /**
-     * Returns the class of the user
+     * Returns the class of the user.
+     *
      * @return string
      */
     public function getClass();
 
     /**
-     * Returns the username
+     * Returns the username.
+     *
      * @return string
      */
     public function getUsername();
 
     /**
-     * Returns the series
+     * Returns the series.
+     *
      * @return string
      */
     public function getSeries();
 
     /**
-     * Returns the token value
+     * Returns the token value.
+     *
      * @return string
      */
     public function getTokenValue();
 
     /**
-     * Returns the last time the cookie was used
+     * Returns the time the token was last used.
+     *
      * @return \DateTime
      */
     public function getLastUsed();

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

@@ -74,6 +74,9 @@ abstract class AbstractToken implements TokenInterface
         return (string) $this->user;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function getUser()
     {
         return $this->user;

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

@@ -18,7 +18,6 @@ use Symfony\Component\Security\Core\Role\RoleInterface;
  *
  * @author Fabien Potencier <fabien@symfony.com>
  */
-
 class AnonymousToken extends AbstractToken
 {
     private $key;

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

@@ -41,11 +41,19 @@ class PreAuthenticatedToken extends AbstractToken
         }
     }
 
+    /**
+     * Returns the provider key.
+     *
+     * @return string The provider key
+     */
     public function getProviderKey()
     {
         return $this->providerKey;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function getCredentials()
     {
         return $this->credentials;
@@ -61,11 +69,17 @@ class PreAuthenticatedToken extends AbstractToken
         $this->credentials = null;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function serialize()
     {
         return serialize(array($this->credentials, $this->providerKey, parent::serialize()));
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function unserialize($str)
     {
         list($this->credentials, $this->providerKey, $parentStr) = unserialize($str);

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

@@ -51,6 +51,9 @@ class RememberMeToken extends AbstractToken
         parent::setAuthenticated(true);
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function setAuthenticated($authenticated)
     {
         if ($authenticated) {
@@ -60,16 +63,29 @@ class RememberMeToken extends AbstractToken
         parent::setAuthenticated(false);
     }
 
+    /**
+     * Returns the provider key.
+     *
+     * @return string The provider key
+     */
     public function getProviderKey()
     {
         return $this->providerKey;
     }
 
+    /**
+     * Returns the key.
+     *
+     * @return string The Key
+     */
     public function getKey()
     {
         return $this->key;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function getCredentials()
     {
         return '';

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

@@ -60,11 +60,19 @@ class UsernamePasswordToken extends AbstractToken
         parent::setAuthenticated(false);
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function getCredentials()
     {
         return $this->credentials;
     }
 
+    /**
+     * Returns the provider key.
+     *
+     * @return string The provider key
+     */
     public function getProviderKey()
     {
         return $this->providerKey;

src/Symfony/Component/Security/Core/Role/RoleHierarchy.php

@@ -34,11 +34,7 @@ class RoleHierarchy implements RoleHierarchyInterface
     }
 
     /**
-     * Returns an array of all roles reachable by the given ones.
-     *
-     * @param RoleInterface[] $roles An array of RoleInterface instances
-     *
-     * @return RoleInterface[] An array of RoleInterface instances
+     * {@inheritdoc}
      */
     public function getReachableRoles(array $roles)
     {

src/Symfony/Component/Security/Core/Role/RoleHierarchyInterface.php

@@ -19,7 +19,7 @@ namespace Symfony\Component\Security\Core\Role;
 interface RoleHierarchyInterface
 {
     /**
-     * Returns an array of all reachable roles.
+     * Returns an array of all reachable roles by the given ones.
      *
      * Reachable roles are the roles directly assigned but also all roles that
      * are transitively reachable from them in the role hierarchy.

src/Symfony/Component/Security/Core/SecurityContext.php

@@ -46,14 +46,9 @@ class SecurityContext implements SecurityContextInterface
     }
 
     /**
-     * Checks if the attributes are granted against the current token.
+     * {@inheritdoc}
      *
      * @throws AuthenticationCredentialsNotFoundException when the security context has no authentication token.
-     *
-     * @param mixed      $attributes
-     * @param mixed|null $object
-     *
-     * @return Boolean
      */
     final public function isGranted($attributes, $object = null)
     {
@@ -73,9 +68,7 @@ class SecurityContext implements SecurityContextInterface
     }
 
     /**
-     * Gets the currently authenticated token.
-     *
-     * @return TokenInterface|null A TokenInterface instance or null if no authentication information is available
+     * {@inheritdoc}
      */
     public function getToken()
     {
@@ -83,9 +76,7 @@ class SecurityContext implements SecurityContextInterface
     }
 
     /**
-     * Sets the currently authenticated token.
-     *
-     * @param TokenInterface $token A TokenInterface token, or null if no further authentication information should be stored
+     * {@inheritdoc}
      */
     public function setToken(TokenInterface $token = null)
     {

src/Symfony/Component/Security/Core/SecurityContextInterface.php

@@ -34,14 +34,14 @@ interface SecurityContextInterface
     /**
      * Sets the authentication token.
      *
-     * @param TokenInterface $token
+     * @param TokenInterface $token A TokenInterface token, or null if no further authentication information should be stored
      */
     public function setToken(TokenInterface $token = null);
 
     /**
      * Checks if the attributes are granted against the current authentication token and optionally supplied object.
      *
-     * @param array $attributes
+     * @param mixed $attributes
      * @param mixed $object
      *
      * @return Boolean

src/Symfony/Component/Security/Core/Validator/Constraints/UserPassword.php

@@ -21,6 +21,9 @@ class UserPassword extends Constraint
     public $message = 'This value should be the user current password.';
     public $service = 'security.validator.user_password';
 
+    /**
+     * {@inheritdoc}
+     */
     public function validatedBy()
     {
         return $this->service;

src/Symfony/Component/Security/Core/Validator/Constraints/UserPasswordValidator.php

@@ -29,6 +29,9 @@ class UserPasswordValidator extends ConstraintValidator
         $this->encoderFactory = $encoderFactory;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function validate($password, Constraint $constraint)
     {
         $user = $this->securityContext->getToken()->getUser();