acl: pylint fixes and docs (ansible#30841)

This PR includes;
- pylint fixes
- Documentation updates

lib/ansible/modules/files/acl.py

@@ -20,113 +20,101 @@
     - Sets and retrieves file ACL information.
 options:
   path:
-    required: true
-    default: null
     description:
       - The full path of the file or object.
-    aliases: ['name']
+    aliases: [ name ]
+    required: true
 
   state:
-    required: false
-    default: query
-    choices: [ 'query', 'present', 'absent' ]
     description:
       - defines whether the ACL should be present or not.  The C(query) state gets the current acl without changing it, for use in 'register' operations.
+    choices: [ absent, present, query ]
+    default: query
 
   follow:
-    required: false
-    default: yes
-    choices: [ 'yes', 'no' ]
     description:
       - whether to follow symlinks on the path if a symlink is encountered.
+    type: bool
+    default: 'yes'
 
   default:
-    version_added: "1.5"
-    required: false
-    default: no
-    choices: [ 'yes', 'no' ]
     description:
       - if the target is a directory, setting this to yes will make it the default acl for entities created inside the directory. It causes an error if
         path is a file.
+    type: bool
+    default: 'no'
+    version_added: "1.5"
 
   entity:
-    version_added: "1.5"
-    required: false
     description:
       - actual user or group that the ACL applies to when matching entity types user or group are selected.
+    version_added: "1.5"
 
   etype:
-    version_added: "1.5"
-    required: false
-    default: null
-    choices: [ 'user', 'group', 'mask', 'other' ]
     description:
       - the entity type of the ACL to apply, see setfacl documentation for more info.
+    choices: [ group, mask, other, user ]
+    version_added: "1.5"
 
   permissions:
-    version_added: "1.5"
-    required: false
-    default: null
     description:
       - Permissions to apply/remove can be any combination of r, w and  x (read, write and execute respectively)
+    version_added: "1.5"
 
   entry:
-    required: false
-    default: null
     description:
       - DEPRECATED. The acl to set or remove.  This must always be quoted in the form of '<etype>:<qualifier>:<perms>'.  The qualifier may be empty for
         some types, but the type and perms are always required. '-' can be used as placeholder when you do not care about permissions. This is now
         superseded by entity, type and permissions fields.
 
   recursive:
-    version_added: "2.0"
-    required: false
-    default: no
-    choices: [ 'yes', 'no' ]
     description:
       - Recursively sets the specified ACL (added in Ansible 2.0). Incompatible with C(state=query).
+    type: bool
+    default: 'no'
+    version_added: "2.0"
 author:
-    - "Brian Coca (@bcoca)"
-    - "Jérémie Astori (@astorije)"
+    - Brian Coca (@bcoca)
+    - Jérémie Astori (@astorije)
 notes:
     - The "acl" module requires that acls are enabled on the target filesystem and that the setfacl and getfacl binaries are installed.
     - As of Ansible 2.0, this module only supports Linux distributions.
     - As of Ansible 2.3, the I(name) option has been changed to I(path) as default, but I(name) still works as well.
 '''
 
 EXAMPLES = '''
-# Grant user Joe read access to a file
-- acl:
+- name: Grant user Joe read access to a file
+  acl:
     path: /etc/foo.conf
     entity: joe
     etype: user
     permissions: r
     state: present
 
-# Removes the acl for Joe on a specific file
-- acl:
+- name: Removes the acl for Joe on a specific file
+  acl:
     path: /etc/foo.conf
     entity: joe
     etype: user
     state: absent
 
-# Sets default acl for joe on foo.d
-- acl:
+- name: Sets default acl for joe on foo.d
+  acl:
     path: /etc/foo.d
     entity: joe
     etype: user
     permissions: rw
     default: yes
     state: present
 
-# Same as previous but using entry shorthand
-- acl:
+- name: Same as previous but using entry shorthand
+  acl:
     path: /etc/foo.d
     entry: "default:user:joe:rw-"
     state: present
 
-# Obtain the acl for a specific file
-- acl:
+- name: Obtain the acl for a specific file
+  acl:
     path: /etc/foo.conf
   register: acl_info
 '''
@@ -140,6 +128,7 @@
 '''
 
 import os
+
 from ansible.module_utils.basic import AnsibleModule, get_platform
 from ansible.module_utils.pycompat24 import get_exception
 
@@ -178,10 +167,11 @@ def build_entry(etype, entity, permissions=None, use_nfsv4_acls=False):
     '''Builds and returns an entry string. Does not include the permissions bit if they are not provided.'''
     if use_nfsv4_acls:
         return ':'.join([etype, entity, permissions, 'allow'])
+
     if permissions:
         return etype + ':' + entity + ':' + permissions
-    else:
-        return etype + ':' + entity
+
+    return etype + ':' + entity
 
 
 def build_command(module, mode, path, follow, default, recursive, entry=''):
@@ -250,8 +240,8 @@ def run_acl(module, cmd, check_rc=True):
     if lines and not lines[-1].split():
         # trim last line only when it is empty
         return lines[:-1]
-    else:
-        return lines
+
+    return lines
 
 
 def main():