added info regarding registry acl's (#28814)

lib/ansible/modules/windows/win_acl.py

@@ -32,85 +32,61 @@ DOCUMENTATION = r'''
 ---
 module: win_acl
 version_added: "2.0"
-short_description: Set file/directory permissions for a system user or group.
+short_description: Set file/directory/registry permissions for a system user or group
 description:
-     - Add or remove rights/permissions for a given user or group for the specified src file or folder.
-     - If adding ACL's for AppPool identities (available since 2.3), the Windows "Feature Web-Scripting-Tools" must be enabled
+- Add or remove rights/permissions for a given user or group for the specified
+  file, folder, registry key or AppPool identifies.
+- If adding ACL's for AppPool identities (available since 2.3), the Windows
+  Feature "Web-Scripting-Tools" must be enabled.
 options:
   path:
     description:
-      - File or Directory
+    - The path to the file or directory.
     required: yes
   user:
     description:
-      - User or Group to add specified rights to act on src file/folder
+    - User or Group to add specified rights to act on src file/folder or
+      registry key.
     required: yes
-    default: none
   state:
     description:
-      - Specify whether to add C(present) or remove C(absent) the specified access rule
-    required: no
-    choices:
-      - present
-      - absent
+    - Specify whether to add C(present) or remove C(absent) the specified access rule.
+    choices: [ absent, present ]
     default: present
   type:
     description:
-      - Specify whether to allow or deny the rights specified
+    - Specify whether to allow or deny the rights specified.
     required: yes
-    choices:
-      - allow
-      - deny
-    default: none
+    choices: [ allow, deny ]
   rights:
     description:
-      - The rights/permissions that are to be allowed/denyed for the specified user or group for the given src file or directory.
-        Can be entered as a comma separated list (Ex. "Modify, Delete, ExecuteFile").  For more information on the choices see MSDN FileSystemRights
-        Enumeration.
+    - The rights/permissions that are to be allowed/denied for the specified
+      user or group for the item at C(path).
+    - If C(path) is a file or directory, rights can be any right under MSDN
+      FileSystemRights U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.filesystemrights=.aspx).
+    - If C(path) is a registry key, rights can be any right under MSDN
+      RegistryRights U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.registryrights.aspx).
     required: yes
-    choices:
-      - AppendData
-      - ChangePermissions
-      - Delete
-      - DeleteSubdirectoriesAndFiles
-      - ExecuteFile
-      - FullControl
-      - ListDirectory
-      - Modify
-      - Read
-      - ReadAndExecute
-      - ReadAttributes
-      - ReadData
-      - ReadExtendedAttributes
-      - ReadPermissions
-      - Synchronize
-      - TakeOwnership
-      - Traverse
-      - Write
-      - WriteAttributes
-      - WriteData
-      - WriteExtendedAttributes
-    default: none
   inherit:
     description:
-      - Inherit flags on the ACL rules.  Can be specified as a comma separated list (Ex. "ContainerInherit, ObjectInherit").  For more information on
-        the choices see MSDN InheritanceFlags Enumeration.
-    required: no
-    choices:
-      - ContainerInherit
-      - ObjectInherit
-      - None
-    default: For Leaf File, None; For Directory, ContainerInherit, ObjectInherit;
+    - Inherit flags on the ACL rules.
+    - Can be specified as a comma separated list, e.g. C(ContainerInherit),
+      C(ObjectInherit).
+    - For more information on the choices see MSDN InheritanceFlags enumeration
+      at U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.inheritanceflags.aspx).
+    choices: [ ContainerInherit, None, ObjectInherit ]
+    default: For Leaf File, 'None'; For Directory, 'ContainerInherit, ObjectInherit';
   propagation:
     description:
-      - Propagation flag on the ACL rules.  For more information on the choices see MSDN PropagationFlags Enumeration.
-    required: no
-    choices:
-      - None
-      - NoPropagateInherit
-      - InheritOnly
+    - Propagation flag on the ACL rules.
+    - For more information on the choices see MSDN PropagationFlags enumeration
+      at U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.propagationflags.aspx).
+    choices: [ InheritOnly, None, NoPropagateInherit ]
     default: "None"
-author: Phil Schwartz (@schwartzmx), Trond Hindenes (@trondhindenes), Hans-Joachim Kliemeck (@h0nIg)
+author:
+- Phil Schwartz (@schwartzmx)
+- Trond Hindenes (@trondhindenes)
+- Hans-Joachim Kliemeck (@h0nIg)
 '''
 
 EXAMPLES = r'''
@@ -131,7 +107,16 @@ EXAMPLES = r'''
     inherit: ContainerInherit, ObjectInherit
     propagation: 'None'
 
-# Remove previously added rule for IIS_IUSRS
+- name: set registry key right
+  win_acl:
+    path: HKCU:\Bovine\Key
+    user: BUILTIN\Users
+    rights: EnumerateSubKeys
+    type: allow
+    state: present
+    inherit: ContainerInherit, ObjectInherit
+    propagation: 'None'
+
 - name: Remove FullControl AccessRule for IIS_IUSRS
   win_acl:
     path: C:\inetpub\wwwroot\MySite
@@ -142,8 +127,7 @@ EXAMPLES = r'''
     inherit: ContainerInherit, ObjectInherit
     propagation: 'None'
 
-# Deny Intern
-- name: Deny Deny
+- name: Deny Intern
   win_acl:
     path: C:\Administrator\Documents
     user: Intern