merged branch raziel057/COMPONENT_Form (PR #5888)

This PR was squashed before being merged into the master branch (closes #5888).

Commits
-------

2379d86 CS Fixes - Replaced "array of type" by "Type[]" in PHPDoc block

Discussion
----------

CS Fixes - Replaced "array of type" by "Type[]" in PHPDoc block

Bug fix: no
Feature addition: no
Backwards compatibility break: no
Symfony2 tests pass: no (but tests doesn't pass on master too). See Travis.
License of the code: MIT
Documentation PR: Not Applicable
Status: Finished

To improve support of the eclipse PDT pluggin (for autocompletion), I propose to change the array notation in PHPDoc blocks to match the phpDocumentor notation for "array of type".

Modifications are made for the following components:
- BrowserKit
- ClassLoader
- Config
- Console
- CssSelector
- DependencyInjection
- DomCrawler
- EventDispatcher (no changes)
- Filesystem (no changes)
- Finder
- Form
- HttpFoundation
- HttpKernel
- Locale
- OptionResolver (no changes)
- Process (no changes)
- Routing (no changes)
- Serializer (no changes)
- Templating
- Translation
- Validator
- Yaml (no changes)
- Security
- Stopwatch (no changes)

See Proposal https://github.com/symfony/symfony/pull/5852

---------------------------------------------------------------------------

by pborreli at 2012-11-01T15:19:27Z

will you make a PR for each component ? why not only one PR with one commit for each component instead ?

---------------------------------------------------------------------------

by raziel057 at 2012-11-01T15:32:39Z

Ok, I'm going try to do it.

---------------------------------------------------------------------------

by raziel057 at 2012-11-01T16:12:56Z

I would like to rename my branch from COMPONENT_Form to changes-phpdoc (as all modifications would be commited in only one branch), so I tried to execute the following command but I have an error.

git remote rename COMPONENT_Form changes-phpdoc
error: Could not rename config section 'remote.COMPONENT_Form' to 'remote.changes-phpdoc'

Do you know how to do it?

---------------------------------------------------------------------------

by pborreli at 2012-11-01T16:14:26Z

don't rename it, you will have to close and make another PR which is useless here, just edit the title.

---------------------------------------------------------------------------

by stof at 2012-11-01T16:16:17Z

and ``git remote rename`` is about renaming a remote repo, not a branch

---------------------------------------------------------------------------

by raziel057 at 2012-11-03T11:36:02Z

Is it normal that all my commit are duplicated? I would like just update my master and merge with my branch.

---------------------------------------------------------------------------

by fabpot at 2012-11-06T10:22:55Z

@raziel057 Can you rebase on master? That should fix your problem.

---------------------------------------------------------------------------

by fabpot at 2012-11-09T13:28:53Z

@raziel057 Can you finish this PR?

---------------------------------------------------------------------------

by Tobion at 2012-11-09T13:34:45Z

I'll do it for the routing component this evening because I know it by heart. ^^

---------------------------------------------------------------------------

by raziel057 at 2012-11-09T15:06:26Z

@Tobion ok Thanks!

@fabpot Yes, I will try to finish it this week end.

---------------------------------------------------------------------------

by raziel057 at 2012-11-11T13:04:07Z

@Tobion Did you already change PHPDoc in the Routing component?

---------------------------------------------------------------------------

by Tobion at 2012-11-11T15:21:18Z

@raziel057 Yes I'm working on it.

---------------------------------------------------------------------------

by Tobion at 2012-11-12T15:16:31Z

@raziel057 Done. See #5994

9 files changed, 48 insertions, 29 deletions

diff --git a/Acl/Domain/AclCollectionCache.php b/Acl/Domain/AclCollectionCache.php
index 88c017c..d3a4b37 100644
--- a/Acl/Domain/AclCollectionCache.php
+++ b/Acl/Domain/AclCollectionCache.php
@@ -44,8 +44,8 @@ class AclCollectionCache
      * Batch loads ACLs for an entire collection; thus, it reduces the number
      * of required queries considerably.
      *
-     * @param mixed $collection anything that can be passed to foreach()
-     * @param array $tokens     an array of TokenInterface implementations
+     * @param mixed            $collection anything that can be passed to foreach()
+     * @param TokenInterface[] $tokens     an array of TokenInterface implementations
      */
     public function cache($collection, array $tokens = array())
     {
diff --git a/Acl/Domain/PermissionGrantingStrategy.php b/Acl/Domain/PermissionGrantingStrategy.php
index 09e227c..e075861 100644
--- a/Acl/Domain/PermissionGrantingStrategy.php
+++ b/Acl/Domain/PermissionGrantingStrategy.php
@@ -16,6 +16,7 @@ use Symfony\Component\Security\Acl\Model\AclInterface;
 use Symfony\Component\Security\Acl\Model\AuditLoggerInterface;
 use Symfony\Component\Security\Acl\Model\EntryInterface;
 use Symfony\Component\Security\Acl\Model\PermissionGrantingStrategyInterface;
+use Symfony\Component\Security\Acl\Model\SecurityIdentityInterface;
 
 /**
  * The permission granting strategy to apply to the access control list.
@@ -123,11 +124,12 @@ class PermissionGrantingStrategy implements PermissionGrantingStrategyInterface
      * permission/identity combinations are left. Finally, we will either throw
      * an NoAceFoundException, or deny access.
      *
-     * @param AclInterface $acl
-     * @param array        $aces               An array of ACE to check against
-     * @param array        $masks              An array of permission masks
-     * @param array        $sids               An array of SecurityIdentityInterface implementations
-     * @param Boolean      $administrativeMode True turns off audit logging
+     * @param AclInterface                $acl
+     * @param EntryInterface[]            $aces               An array of ACE to check against
+     * @param array                       $masks              An array of permission masks
+     * @param SecurityIdentityInterface[] $sids               An array of SecurityIdentityInterface implementations
+     * @param Boolean                     $administrativeMode True turns off audit logging
+     *
      * @return Boolean true, or false; either granting, or denying access respectively.
      */
     private function hasSufficientPermissions(AclInterface $acl, array $aces, array $masks, array $sids, $administrativeMode)
@@ -186,7 +188,10 @@ class PermissionGrantingStrategy implements PermissionGrantingStrategyInterface
      *
      * @param integer        $requiredMask
      * @param EntryInterface $ace
+     *
      * @return Boolean
+     *
+     * @throws \RuntimeException if the ACE strategy is not supported
      */
     private function isAceApplicable($requiredMask, EntryInterface $ace)
     {
diff --git a/Acl/Model/AclProviderInterface.php b/Acl/Model/AclProviderInterface.php
index bdb40b7..4be49bf 100644
--- a/Acl/Model/AclProviderInterface.php
+++ b/Acl/Model/AclProviderInterface.php
@@ -23,6 +23,7 @@ interface AclProviderInterface
      *
      * @param ObjectIdentityInterface $parentOid
      * @param Boolean                 $directChildrenOnly
+     *
      * @return array returns an array of child 'ObjectIdentity's
      */
     public function findChildren(ObjectIdentityInterface $parentOid, $directChildrenOnly = false);
@@ -30,20 +31,24 @@ interface AclProviderInterface
     /**
      * Returns the ACL that belongs to the given object identity
      *
-     * @throws AclNotFoundException when there is no ACL
-     * @param ObjectIdentityInterface $oid
-     * @param array                   $sids
+     * @param ObjectIdentityInterface     $oid
+     * @param SecurityIdentityInterface[] $sids
+     *
      * @return AclInterface
+     *
+     * @throws AclNotFoundException when there is no ACL
      */
     public function findAcl(ObjectIdentityInterface $oid, array $sids = array());
 
     /**
      * Returns the ACLs that belong to the given object identities
      *
-     * @throws AclNotFoundException when we cannot find an ACL for all identities
-     * @param array $oids an array of ObjectIdentityInterface implementations
-     * @param array $sids an array of SecurityIdentityInterface implementations
+     * @param ObjectIdentityInterface[]   $oids an array of ObjectIdentityInterface implementations
+     * @param SecurityIdentityInterface[] $sids an array of SecurityIdentityInterface implementations
+     *
      * @return \SplObjectStorage mapping the passed object identities to ACLs
+     *
+     * @throws AclNotFoundException when we cannot find an ACL for all identities
      */
     public function findAcls(array $oids, array $sids = array());
 }
diff --git a/Acl/Model/SecurityIdentityRetrievalStrategyInterface.php b/Acl/Model/SecurityIdentityRetrievalStrategyInterface.php
index c20f04b..5bb7915 100644
--- a/Acl/Model/SecurityIdentityRetrievalStrategyInterface.php
+++ b/Acl/Model/SecurityIdentityRetrievalStrategyInterface.php
@@ -28,7 +28,8 @@ interface SecurityIdentityRetrievalStrategyInterface
      * least specific.
      *
      * @param TokenInterface $token
-     * @return array of SecurityIdentityInterface implementations
+     *
+     * @return SecurityIdentityInterface[] An array of SecurityIdentityInterface implementations
      */
     public function getSecurityIdentities(TokenInterface $token);
 }
diff --git a/Core/Authentication/Token/AbstractToken.php b/Core/Authentication/Token/AbstractToken.php
index ed6e8de..68cbb79 100644
--- a/Core/Authentication/Token/AbstractToken.php
+++ b/Core/Authentication/Token/AbstractToken.php
@@ -33,7 +33,7 @@ abstract class AbstractToken implements TokenInterface
     /**
      * Constructor.
      *
-     * @param Role[] $roles An array of roles
+     * @param RoleInterface[] $roles An array of roles
      */
     public function __construct(array $roles = array())
     {
diff --git a/Core/Authentication/Token/AnonymousToken.php b/Core/Authentication/Token/AnonymousToken.php
index ecdd4cc..9b0a084 100644
--- a/Core/Authentication/Token/AnonymousToken.php
+++ b/Core/Authentication/Token/AnonymousToken.php
@@ -24,9 +24,9 @@ class AnonymousToken extends AbstractToken
     /**
      * Constructor.
      *
-     * @param string $key   The key shared with the authentication provider
-     * @param string $user  The user
-     * @param Role[] $roles An array of roles
+     * @param string          $key   The key shared with the authentication provider
+     * @param string          $user  The user
+     * @param RoleInterface[] $roles An array of roles
      */
     public function __construct($key, $user, array $roles = array())
     {
@@ -66,9 +66,9 @@ class AnonymousToken extends AbstractToken
     /**
      * {@inheritDoc}
      */
-    public function unserialize($str)
+    public function unserialize($serialized)
     {
-        list($this->key, $parentStr) = unserialize($str);
+        list($this->key, $parentStr) = unserialize($serialized);
         parent::unserialize($parentStr);
     }
 }
diff --git a/Core/Authentication/Token/TokenInterface.php b/Core/Authentication/Token/TokenInterface.php
index dec31d5..11f69da 100644
--- a/Core/Authentication/Token/TokenInterface.php
+++ b/Core/Authentication/Token/TokenInterface.php
@@ -11,6 +11,8 @@
 
 namespace Symfony\Component\Security\Core\Authentication\Token;
 
+use Symfony\Component\Security\Core\Role\RoleInterface;
+
 /**
  * TokenInterface is the interface for the user authentication information.
  *
@@ -31,7 +33,7 @@ interface TokenInterface extends \Serializable
     /**
      * Returns the user roles.
      *
-     * @return Role[] An array of Role instances.
+     * @return RoleInterface[] An array of RoleInterface instances.
      */
     public function getRoles();
 
diff --git a/Core/Authentication/Token/UsernamePasswordToken.php b/Core/Authentication/Token/UsernamePasswordToken.php
index 95eec54..d6e3998 100644
--- a/Core/Authentication/Token/UsernamePasswordToken.php
+++ b/Core/Authentication/Token/UsernamePasswordToken.php
@@ -24,10 +24,10 @@ class UsernamePasswordToken extends AbstractToken
     /**
      * Constructor.
      *
-     * @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
+     * @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 RoleInterface[] $roles       An array of roles
      *
      * @throws \InvalidArgumentException
      */
@@ -78,14 +78,20 @@ class UsernamePasswordToken extends AbstractToken
         $this->credentials = null;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function serialize()
     {
         return serialize(array($this->credentials, $this->providerKey, parent::serialize()));
     }
 
-    public function unserialize($str)
+    /**
+     * {@inheritdoc}
+     */
+    public function unserialize($serialized)
     {
-        list($this->credentials, $this->providerKey, $parentStr) = unserialize($str);
+        list($this->credentials, $this->providerKey, $parentStr) = unserialize($serialized);
         parent::unserialize($parentStr);
     }
 }
diff --git a/Core/Role/RoleHierarchyInterface.php b/Core/Role/RoleHierarchyInterface.php
index c495a7f..2ea6ca3 100644
--- a/Core/Role/RoleHierarchyInterface.php
+++ b/Core/Role/RoleHierarchyInterface.php
@@ -24,9 +24,9 @@ interface RoleHierarchyInterface
      * Reachable roles are the roles directly assigned but also all roles that
      * are transitively reachable from them in the role hierarchy.
      *
-     * @param array $roles An array of directly assigned roles
+     * @param RoleInterface[] $roles An array of directly assigned roles
      *
-     * @return array An array of all reachable roles
+     * @return RoleInterface[] An array of all reachable roles
      */
     public function getReachableRoles(array $roles);
 }