Update the docstring for setPermissions to be clearer what 2 parameters do (#1164)

Author: BryanFauble

synapseclient/client.py

@@ -2908,9 +2908,18 @@ def setPermissions(
                             and '273949' is for public access. None implies public access.
             accessType: Type of permission to be granted. One or more of CREATE, READ, DOWNLOAD, UPDATE,
                             DELETE, CHANGE_PERMISSIONS
-            modify_benefactor: Set as True when modifying a benefactor's ACL
-            warn_if_inherits: Set as False, when creating a new ACL.
-                                Trying to modify the ACL of an Entity that inherits its ACL will result in a warning
+            modify_benefactor: Set as True when modifying a benefactor's ACL. The term
+                'benefactor' is used to indicate which Entity an Entity inherits its
+                ACL from. For example, a newly created Project will be its own
+                benefactor, while a new FileEntity's benefactor will start off as its
+                containing Project. If the entity already has local sharing settings
+                the benefactor would be itself. It may also be the immediate parent,
+                somewhere in the parent tree, or the project itself.
+            warn_if_inherits: When `modify_benefactor` is True, this does not have any
+                effect. When `modify_benefactor` is False, and `warn_if_inherits` is
+                True, a warning log message is produced if the benefactor for the
+                entity you passed into the function is not itself, i.e., it's the
+                parent folder, or another entity in the parent tree.
             overwrite: By default this function overwrites existing permissions for the specified user.
                         Set this flag to False to add new permissions non-destructively.
 

synapseclient/models/mixins/access_control.py

@@ -109,9 +109,18 @@ async def set_permissions_async(
                 READ, DOWNLOAD, UPDATE, DELETE, CHANGE_PERMISSIONS.
 
                 **Defaults to ['READ', 'DOWNLOAD']**
-            modify_benefactor: Set as True when modifying a benefactor's ACL
-            warn_if_inherits: Set as False, when creating a new ACL. Trying to modify
-                the ACL of an Entity that inherits its ACL will result in a warning
+            modify_benefactor: Set as True when modifying a benefactor's ACL. The term
+                'benefactor' is used to indicate which Entity an Entity inherits its
+                ACL from. For example, a newly created Project will be its own
+                benefactor, while a new FileEntity's benefactor will start off as its
+                containing Project. If the entity already has local sharing settings
+                the benefactor would be itself. It may also be the immediate parent,
+                somewhere in the parent tree, or the project itself.
+            warn_if_inherits: When `modify_benefactor` is True, this does not have any
+                effect. When `modify_benefactor` is False, and `warn_if_inherits` is
+                True, a warning log message is produced if the benefactor for the
+                entity you passed into the function is not itself, i.e., it's the
+                parent folder, or another entity in the parent tree.
             overwrite: By default this function overwrites existing permissions for
                 the specified user. Set this flag to False to add new permissions
                 non-destructively.

synapseclient/models/protocols/access_control_protocol.py

@@ -87,9 +87,18 @@ def set_permissions(
                 READ, DOWNLOAD, UPDATE, DELETE, CHANGE_PERMISSIONS.
 
                 **Defaults to ['READ', 'DOWNLOAD']**
-            modify_benefactor: Set as True when modifying a benefactor's ACL
-            warn_if_inherits: Set as False, when creating a new ACL. Trying to modify
-                the ACL of an Entity that inherits its ACL will result in a warning
+            modify_benefactor: Set as True when modifying a benefactor's ACL. The term
+                'benefactor' is used to indicate which Entity an Entity inherits its
+                ACL from. For example, a newly created Project will be its own
+                benefactor, while a new FileEntity's benefactor will start off as its
+                containing Project. If the entity already has local sharing settings
+                the benefactor would be itself. It may also be the immediate parent,
+                somewhere in the parent tree, or the project itself.
+            warn_if_inherits: When `modify_benefactor` is True, this does not have any
+                effect. When `modify_benefactor` is False, and `warn_if_inherits` is
+                True, a warning log message is produced if the benefactor for the
+                entity you passed into the function is not itself, i.e., it's the
+                parent folder, or another entity in the parent tree.
             overwrite: By default this function overwrites existing permissions for
                 the specified user. Set this flag to False to add new permissions
                 non-destructively.