Merged V2.0 to HEAD

5146: AR-1122
   5148: AR-1116
   5149: RM-5
   5152: AR-1167
   5153: WCM-324
   5154: WCM-325, WCM-301, WCM-258, WCM-25, WCM-320
   5156: WCM-338
   5158: AR-1164
   5169: AR-1216
   5177: WCM-328


git-svn-id: https://svn.alfresco.com/repos/alfresco-enterprise/alfresco/HEAD/root@5327 c4b6b30b-aa2e-2d43-bbcb-ca4b014f7261

source/java/org/alfresco/service/cmr/security/PermissionService.java

@@ -212,7 +212,7 @@ public interface PermissionService
      * Delete all permission for the given authority.
      * 
      * @param nodeRef
-     * @param authority
+     * @param authority (if null then this will match all authorities)
      */
     @Auditable(key = Auditable.Key.ARG_0, parameters = {"nodeRef", "authority"})
     public void clearPermission(NodeRef nodeRef, String authority);
@@ -220,9 +220,17 @@ public interface PermissionService
     /**
      * Find and delete a access control entry by node, authentication and permission.
      * 
+     * It is possible to delete 
+     * <ol>
+     * <li> a specific permission;
+     * <li> all permissions for an authority (if the permission is null); 
+     * <li> entries for all authorities that have a specific permission (if the authority is null); and 
+     * <li> all permissions set for the node (if both the permission and authority are null).
+     * </ol> 
+     * 
      * @param nodeRef the node that the entry applies to
-     * @param authority the authority recipient
-     * @param permission the entry permission
+     * @param authority the authority recipient (if null then this will match all authorities)
+     * @param permission the entry permission (if null then this will match all permissions)
      */
     @Auditable(key = Auditable.Key.ARG_0, parameters = {"nodeRef", "authority", "permission"})
     public void deletePermission(NodeRef nodeRef, String authority, String permission);