minor #12774 Docblock Fixes (GrahamCampbell)

This PR was merged into the 2.3 branch.

Discussion
----------

Docblock Fixes

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | no
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | N/A
| License       | MIT
| Doc PR        | N/A

##### This pull request fixes the docblock alignment as requested in #12760.

It was also necessary for me to ensure the `@return` annotations were correctly separated in order to accurately align the `@param` annotations.

Commits
-------

443307e Docblock fixes

8 files changed, 58 insertions, 45 deletions

diff --git a/Acl/Model/AclCacheInterface.php b/Acl/Model/AclCacheInterface.php
index 4673e01..03431db 100644
--- a/Acl/Model/AclCacheInterface.php
+++ b/Acl/Model/AclCacheInterface.php
@@ -37,7 +37,8 @@ interface AclCacheInterface
     /**
      * Retrieves an ACL for the given object identity primary key from the cache
      *
-     * @param int     $primaryKey
+     * @param int $primaryKey
+     *
      * @return AclInterface
      */
     public function getFromCacheById($primaryKey);
@@ -46,6 +47,7 @@ interface AclCacheInterface
      * Retrieves an ACL for the given object identity from the cache
      *
      * @param ObjectIdentityInterface $oid
+     *
      * @return AclInterface
      */
     public function getFromCacheByIdentity(ObjectIdentityInterface $oid);
diff --git a/Acl/Model/AclInterface.php b/Acl/Model/AclInterface.php
index 85a4e83..c5bbf18 100644
--- a/Acl/Model/AclInterface.php
+++ b/Acl/Model/AclInterface.php
@@ -36,6 +36,7 @@ interface AclInterface extends \Serializable
      * Returns all class-field-based ACEs associated with this ACL
      *
      * @param string $field
+     *
      * @return array
      */
     public function getClassFieldAces($field);
@@ -51,6 +52,7 @@ interface AclInterface extends \Serializable
      * Returns all object-field-based ACEs associated with this ACL
      *
      * @param string $field
+     *
      * @return array
      */
     public function getObjectFieldAces($field);
@@ -79,10 +81,11 @@ interface AclInterface extends \Serializable
     /**
      * Determines whether field access is granted
      *
-     * @param string  $field
-     * @param array   $masks
-     * @param array   $securityIdentities
-     * @param bool    $administrativeMode
+     * @param string $field
+     * @param array  $masks
+     * @param array  $securityIdentities
+     * @param bool   $administrativeMode
+     *
      * @return bool
      */
     public function isFieldGranted($field, array $masks, array $securityIdentities, $administrativeMode = false);
@@ -90,10 +93,12 @@ interface AclInterface extends \Serializable
     /**
      * Determines whether access is granted
      *
+     * @param array $masks
+     * @param array $securityIdentities
+     * @param bool  $administrativeMode
+     *
      * @throws NoAceFoundException when no ACE was applicable for this request
-     * @param array   $masks
-     * @param array   $securityIdentities
-     * @param bool    $administrativeMode
+     *
      * @return bool
      */
     public function isGranted(array $masks, array $securityIdentities, $administrativeMode = false);
@@ -102,6 +107,7 @@ interface AclInterface extends \Serializable
      * Whether the ACL has loaded ACEs for all of the passed security identities
      *
      * @param mixed $securityIdentities an implementation of SecurityIdentityInterface, or an array thereof
+     *
      * @return bool
      */
     public function isSidLoaded($securityIdentities);
diff --git a/Acl/Model/AuditableAclInterface.php b/Acl/Model/AuditableAclInterface.php
index f5ed9dd..80b9987 100644
--- a/Acl/Model/AuditableAclInterface.php
+++ b/Acl/Model/AuditableAclInterface.php
@@ -21,38 +21,38 @@ interface AuditableAclInterface extends MutableAclInterface
     /**
      * Updates auditing for class-based ACE
      *
-     * @param int     $index
-     * @param bool    $auditSuccess
-     * @param bool    $auditFailure
+     * @param int  $index
+     * @param bool $auditSuccess
+     * @param bool $auditFailure
      */
     public function updateClassAuditing($index, $auditSuccess, $auditFailure);
 
     /**
      * Updates auditing for class-field-based ACE
      *
-     * @param int     $index
-     * @param string  $field
-     * @param bool    $auditSuccess
-     * @param bool    $auditFailure
+     * @param int    $index
+     * @param string $field
+     * @param bool   $auditSuccess
+     * @param bool   $auditFailure
      */
     public function updateClassFieldAuditing($index, $field, $auditSuccess, $auditFailure);
 
     /**
      * Updates auditing for object-based ACE
      *
-     * @param int     $index
-     * @param bool    $auditSuccess
-     * @param bool    $auditFailure
+     * @param int  $index
+     * @param bool $auditSuccess
+     * @param bool $auditFailure
      */
     public function updateObjectAuditing($index, $auditSuccess, $auditFailure);
 
     /**
      * Updates auditing for object-field-based ACE
      *
-     * @param int     $index
-     * @param string  $field
-     * @param bool    $auditSuccess
-     * @param bool    $auditFailure
+     * @param int    $index
+     * @param string $field
+     * @param bool   $auditSuccess
+     * @param bool   $auditFailure
      */
     public function updateObjectFieldAuditing($index, $field, $auditSuccess, $auditFailure);
 }
diff --git a/Acl/Model/MutableAclInterface.php b/Acl/Model/MutableAclInterface.php
index 8993aa5..f94e909 100644
--- a/Acl/Model/MutableAclInterface.php
+++ b/Acl/Model/MutableAclInterface.php
@@ -24,30 +24,30 @@ interface MutableAclInterface extends AclInterface
     /**
      * Deletes a class-based ACE
      *
-     * @param int     $index
+     * @param int $index
      */
     public function deleteClassAce($index);
 
     /**
      * Deletes a class-field-based ACE
      *
-     * @param int     $index
-     * @param string  $field
+     * @param int    $index
+     * @param string $field
      */
     public function deleteClassFieldAce($index, $field);
 
     /**
      * Deletes an object-based ACE
      *
-     * @param int     $index
+     * @param int $index
      */
     public function deleteObjectAce($index);
 
     /**
      * Deletes an object-field-based ACE
      *
-     * @param int     $index
-     * @param string  $field
+     * @param int    $index
+     * @param string $field
      */
     public function deleteObjectFieldAce($index, $field);
 
@@ -107,7 +107,7 @@ interface MutableAclInterface extends AclInterface
     /**
      * Sets whether entries are inherited
      *
-     * @param bool    $boolean
+     * @param bool $boolean
      */
     public function setEntriesInheriting($boolean);
 
@@ -121,38 +121,38 @@ interface MutableAclInterface extends AclInterface
     /**
      * Updates a class-based ACE
      *
-     * @param int     $index
-     * @param int     $mask
-     * @param string  $strategy if null the strategy should not be changed
+     * @param int    $index
+     * @param int    $mask
+     * @param string $strategy if null the strategy should not be changed
      */
     public function updateClassAce($index, $mask, $strategy = null);
 
     /**
      * Updates a class-field-based ACE
      *
-     * @param int     $index
-     * @param string  $field
-     * @param int     $mask
-     * @param string  $strategy if null the strategy should not be changed
+     * @param int    $index
+     * @param string $field
+     * @param int    $mask
+     * @param string $strategy if null the strategy should not be changed
      */
     public function updateClassFieldAce($index, $field, $mask, $strategy = null);
 
     /**
      * Updates an object-based ACE
      *
-     * @param int     $index
-     * @param int     $mask
-     * @param string  $strategy if null the strategy should not be changed
+     * @param int    $index
+     * @param int    $mask
+     * @param string $strategy if null the strategy should not be changed
      */
     public function updateObjectAce($index, $mask, $strategy = null);
 
     /**
      * Updates an object-field-based ACE
      *
-     * @param int     $index
-     * @param string  $field
-     * @param int     $mask
-     * @param string  $strategy if null the strategy should not be changed
+     * @param int    $index
+     * @param string $field
+     * @param int    $mask
+     * @param string $strategy if null the strategy should not be changed
      */
     public function updateObjectFieldAce($index, $field, $mask, $strategy = null);
 }
diff --git a/Acl/Model/MutableAclProviderInterface.php b/Acl/Model/MutableAclProviderInterface.php
index cb34b72..f5bb198 100644
--- a/Acl/Model/MutableAclProviderInterface.php
+++ b/Acl/Model/MutableAclProviderInterface.php
@@ -21,9 +21,11 @@ interface MutableAclProviderInterface extends AclProviderInterface
     /**
      * Creates a new ACL for the given object identity.
      *
-     * @throws AclAlreadyExistsException when there already is an ACL for the given
-     *                                   object identity
      * @param ObjectIdentityInterface $oid
+     *
+     * @throws AclAlreadyExistsException when there already is an ACL for the given
+     *                                       object identity
+     *
      * @return MutableAclInterface
      */
     public function createAcl(ObjectIdentityInterface $oid);
diff --git a/Acl/Model/ObjectIdentityInterface.php b/Acl/Model/ObjectIdentityInterface.php
index 2ee365f..6574b49 100644
--- a/Acl/Model/ObjectIdentityInterface.php
+++ b/Acl/Model/ObjectIdentityInterface.php
@@ -28,6 +28,7 @@ interface ObjectIdentityInterface
      * Example for Object Equality: $object1->getId() === $object2->getId()
      *
      * @param ObjectIdentityInterface $identity
+     *
      * @return bool
      */
     public function equals(ObjectIdentityInterface $identity);
diff --git a/Acl/Model/ObjectIdentityRetrievalStrategyInterface.php b/Acl/Model/ObjectIdentityRetrievalStrategyInterface.php
index b0f7f78..d5470ae 100644
--- a/Acl/Model/ObjectIdentityRetrievalStrategyInterface.php
+++ b/Acl/Model/ObjectIdentityRetrievalStrategyInterface.php
@@ -22,6 +22,7 @@ interface ObjectIdentityRetrievalStrategyInterface
      * Retrieves the object identity from a domain object
      *
      * @param object $domainObject
+     *
      * @return ObjectIdentityInterface
      */
     public function getObjectIdentity($domainObject);
diff --git a/Acl/Model/PermissionGrantingStrategyInterface.php b/Acl/Model/PermissionGrantingStrategyInterface.php
index 25f1687..7ff475f 100644
--- a/Acl/Model/PermissionGrantingStrategyInterface.php
+++ b/Acl/Model/PermissionGrantingStrategyInterface.php
@@ -25,6 +25,7 @@ interface PermissionGrantingStrategyInterface
      * @param array        $masks
      * @param array        $sids
      * @param bool         $administrativeMode
+     *
      * @return bool
      */
     public function isGranted(AclInterface $acl, array $masks, array $sids, $administrativeMode = false);