Add "pure" state functionality for win_group_membership (#51298)

* add pure state functionality for win_group_membership

* fixing typos in docs

* fix syntax for adding removed array depending on state

* remove trailing whitespace from docs

* fix issue in testing pure (again)

* adding note for pure being added in Ansible 2.8

lib/ansible/modules/windows/win_group_membership.py

@@ -35,8 +35,11 @@ options:
   state:
     description:
       - Desired state of the members in the group.
+      - C(pure) was added in Ansible 2.8.
+      - When C(state) is C(pure), only the members specified will exist,
+        and all other existing members not specified are removed.
     type: str
-    choices: [ absent, present ]
+    choices: [ absent, present, pure ]
     default: present
 seealso:
 - module: win_domain_group
@@ -62,6 +65,13 @@ EXAMPLES = r'''
       - DOMAIN\TestGroup
       - NT AUTHORITY\SYSTEM
     state: absent
+
+- name: Ensure only a domain user exists in a local group
+  win_group_membership:
+    name: Remote Desktop Users
+    members:
+      - DOMAIN\TestUser
+    state: pure
 '''
 
 RETURN = r'''
@@ -71,14 +81,14 @@ name:
     type: str
     sample: Administrators
 added:
-    description: A list of members added when C(state) is C(present); this is
-      empty if no members are added.
+    description: A list of members added when C(state) is C(present) or
+      C(pure); this is empty if no members are added.
     returned: success and C(state) is C(present)
     type: list
     sample: ["SERVERNAME\\NewLocalAdmin", "DOMAIN\\TestUser"]
 removed:
-    description: A list of members removed when C(state) is C(absent); this is
-      empty if no members are removed.
+    description: A list of members removed when C(state) is C(absent) or
+      C(pure); this is empty if no members are removed.
     returned: success and C(state) is C(absent)
     type: list
     sample: ["DOMAIN\\TestGroup", "NT AUTHORITY\\SYSTEM"]