Update module documentation

Update the module docs to try and simplify the the name/identity/path
options, for example what they represent and when they should be used.
Also update the documentation to reflect how these modules should be run
on a Windows target.

plugins/doc_fragments/ad_object.py

@@ -102,25 +102,25 @@ class ModuleDocFragment:
   identity:
     description:
     - The identity of the AD object used to find the AD object to manage.
-    - Must be specified if I(name) is not set, when trying to rename the object
-      with a new I(name), or when trying to move the object into a different
-      I(path).
+    - This must be specified if; I(name) is not set, when trying to rename the
+      object with a new I(name), or when trying to move the object into a
+      different I(path).
     - The identity can be in the form of a GUID representing the C(objectGUID)
       value, the C(userPrincipalName), C(sAMAccountName), C(objectSid), or
       C(distinguishedName).
-    - If omitted, the AD object to managed is selected by the
+    - If omitted, the AD object to manage is selected by the
       C(distinguishedName) using the format C(CN={{ name }},{{ path }}). If
       I(path) is not defined, the C(defaultNamingContext) is used instead.
     type: str
   name:
     description:
-    - The C(name) of the AD object to manage.
-    - If I(identity) is specified, and the name of the object it found does not
-      match this value, the object will be renamed.
-    - This if I(identity) must be set to find the object to manage.
-    - This is not always going to be the same as the C(sAMAccountName) for user
-      objects. It is strictly the C(name) of the object in the path specified.
-      Use I(identity) to select an object to manage by C(sAMAccountName).
+    - The C(name) of the AD object to manage, this is not the C(sAMAccountName)
+      of the object but the LDAP C(cn) or C(name) entry of the object in the
+      path specified. Use I(identity) to select an object to manage by its
+      C(sAMAccountName).
+    - If I(identity) is specified, and the name of the object found by that
+      identity does not match this value, the object will be renamed.
+    - This must be specified if I(identity) is not set.
     type: str
   path:
     description:
@@ -134,8 +134,8 @@ class ModuleDocFragment:
     - The modules M(microsoft.ad.computer), M(microsoft.ad.user), and
       M(microsoft.ad.group) have their own default path that is
       configured on the Active Directory domain controller.
-    - This can be set to C(microsoft.ad.default_path) which will equal the
-      default value used when creating a new object.
+    - This can be set to the literal value C(microsoft.ad.default_path) which
+      will equal the default value used when creating a new object.
     type: str
   protect_from_deletion:
     description:

plugins/modules/computer.py

@@ -184,6 +184,8 @@
 - See R(win_domain_computer migration,ansible_collections.microsoft.ad.docsite.guide_migration.migrated_modules.win_domain_computer)
   for help on migrating from M(community.windows.win_domain_computer) to this
   module.
+- This module must be run on a Windows target host with the C(ActiveDirectory)
+  module installed.
 extends_documentation_fragment:
 - microsoft.ad.ad_object
 - ansible.builtin.action_common_attributes
@@ -223,12 +225,12 @@
 
 - name: Remove linux computer from Active Directory using a windows machine
   microsoft.ad.computer:
-    name: one_linux_server
+    identity: one_linux_server
     state: absent
 
 - name: Add SPNs to computer
   microsoft.ad.computer:
-    name: TheComputer
+    identity: TheComputer
     spn:
       add:
       - HOST/TheComputer
@@ -237,7 +239,7 @@
 
 - name: Remove SPNs on the computer
   microsoft.ad.computer:
-    name: TheComputer
+    identity: TheComputer
     spn:
       remove:
       - HOST/TheComputer
@@ -246,7 +248,7 @@
 
 - name: Set the principals the computer trusts for delegation from
   microsoft.ad.computer:
-    name: TheComputer
+    identity: TheComputer
     delegates:
       set:
       - CN=FileShare,OU=Computers,DC=domain,DC=test

plugins/modules/domain.py

@@ -78,6 +78,8 @@
       Sysvol file will be created.
     - If not set then the default path is C(%SYSTEMROOT%\SYSVOL).
     type: path
+notes:
+- This module must be run on a Windows target host.
 extends_documentation_fragment:
 - ansible.builtin.action_common_attributes
 - ansible.builtin.action_common_attributes.flow

plugins/modules/domain_controller.py

@@ -92,6 +92,7 @@
 - It is highly recommended to set I(reboot=true) to have Ansible manage the host reboot phase as the actions done by
   this module puts the host in a state where it may not be possible for Ansible to reconnect in a subsequent task
   without a reboot.
+- This module must be run on a Windows target host.
 extends_documentation_fragment:
 - ansible.builtin.action_common_attributes
 - ansible.builtin.action_common_attributes.flow

plugins/modules/group.py

@@ -90,6 +90,8 @@
 - See R(win_group migration,ansible_collections.microsoft.ad.docsite.guide_migration.migrated_modules.win_domain_group)
   for help on migrating from M(community.windows.win_domain_group) to this
   module.
+- This module must be run on a Windows target host with the C(ActiveDirectory)
+  module installed.
 extends_documentation_fragment:
 - microsoft.ad.ad_object
 - ansible.builtin.action_common_attributes
@@ -118,12 +120,12 @@
 EXAMPLES = r"""
 - name: Ensure a group exists
   microsoft.ad.group:
-    name: Cow
+    identity: Cow
     scope: global
 
 - name: Remove a group
   microsoft.ad.group:
-    name: Cow
+    identity: Cow
     state: absent
 
 - name: Create a group in a custom path

plugins/modules/membership.py

@@ -72,6 +72,8 @@
     description:
     - When I(state=workgroup), this is the name of the workgroup that the Windows host should be in.
     type: str
+notes:
+- This module must be run on a Windows target host.
 extends_documentation_fragment:
 - ansible.builtin.action_common_attributes
 - ansible.builtin.action_common_attributes.flow

plugins/modules/object.py

@@ -24,6 +24,8 @@
   Directory. It will not validate all the correct defaults are set for each
   type when it is created. If a type specific module is available to manage
   that AD object type it is recommend to use that.
+- This module must be run on a Windows target host with the C(ActiveDirectory)
+  module installed.
 extends_documentation_fragment:
 - microsoft.ad.ad_object
 - ansible.builtin.action_common_attributes

plugins/modules/object_info.py

@@ -94,7 +94,8 @@
   and C(userAccountControl_AnsibleFlags) return property is something set by the module itself as an easy way to view
   what those flags represent. These properties cannot be used as part of the I(filter) or I(ldap_filter) and are
   automatically added if those properties were requested.
-- This must be run on a host that has the ActiveDirectory powershell module installed.
+- This module must be run on a Windows target host with the C(ActiveDirectory)
+  module installed.
 extends_documentation_fragment:
 - ansible.builtin.action_common_attributes
 attributes:

plugins/modules/offline_join.py

@@ -85,6 +85,8 @@
 - Generating a new blob will reset the password of the computer object, take
   care that this isn't called under a computer account that has already been
   joined.
+- This module must be run on a Windows target host with the C(ActiveDirectory)
+  module installed.
 seealso:
 - module: microsoft.ad.domain
 - module: microsoft.ad.membership

plugins/modules/ou.py

@@ -49,6 +49,8 @@
   specified.
 - See R(win_domain_ou migration,ansible_collections.microsoft.ad.docsite.guide_migration.migrated_modules.win_domain_ou)
   for help on migrating from M(community.windows.win_domain_ou) to this module.
+- This module must be run on a Windows target host with the C(ActiveDirectory)
+  module installed.
 extends_documentation_fragment:
 - microsoft.ad.ad_object
 - ansible.builtin.action_common_attributes

plugins/modules/user.py

@@ -104,6 +104,10 @@
     - To clear all group memberships, use I(set) with an empty list.
     - Note that users cannot be removed from their principal group (for
       example, "Domain Users"). Attempting to do so will display a warning.
+    - Each subkey is set to a list of groups objects to add, remove or
+      set as the membership of this AD user respectively. A group can be in
+      the form of a C(distinguishedName), C(objectGUID), C(objectSid), or
+      C(sAMAccountName).
     - See R(Setting list option values,ansible_collections.microsoft.ad.docsite.guide_list_values)
       for more information on how to add/remove/set list options.
     type: dict
@@ -245,6 +249,8 @@
 notes:
 - See R(win_domain_user migration,ansible_collections.microsoft.ad.docsite.guide_migration.migrated_modules.win_domain_user)
   for help on migrating from M(community.windows.win_domain_user) to this module.
+- This module must be run on a Windows target host with the C(ActiveDirectory)
+  module installed.
 extends_documentation_fragment:
 - microsoft.ad.ad_object
 - ansible.builtin.action_common_attributes
@@ -273,7 +279,7 @@
 EXAMPLES = r"""
 - name: Ensure user bob is present with address information
   microsoft.ad.user:
-    name: bob
+    identity: bob
     firstname: Bob
     surname: Smith
     company: BobCo
@@ -293,7 +299,7 @@
 
 - name: Ensure user bob is created and use custom credentials to create the user
   microsoft.ad.user:
-    name: bob
+    identity: bob
     firstname: Bob
     surname: Smith
     password: B0bP4ssw0rd
@@ -304,7 +310,7 @@
 
 - name: Ensure user bob is present in OU ou=test,dc=domain,dc=local
   microsoft.ad.user:
-    name: bob
+    identity: bob
     password: B0bP4ssw0rd
     state: present
     path: ou=test,dc=domain,dc=local
@@ -315,27 +321,27 @@
 
 - name: Ensure user bob is absent
   microsoft.ad.user:
-    name: bob
+    identity: bob
     state: absent
 
 - name: Ensure user has only these spn's defined
   microsoft.ad.user:
-    name: liz.kenyon
+    identity: liz.kenyon
     spn:
       set:
       - MSSQLSvc/us99db-svr95:1433
       - MSSQLSvc/us99db-svr95.vmware.com:1433
 
 - name: Ensure user has spn added
   microsoft.ad.user:
-    name: liz.kenyon
+    identity: liz.kenyon
     spn:
       add:
       - MSSQLSvc/us99db-svr95:2433
 
 - name: Ensure user is created with delegates and spn's defined
   microsoft.ad.user:
-    name: shmemmmy
+    identity: shmemmmy
     password: The3rubberducki33!
     state: present
     groups: