From 9f0f66137f45390b6cde74f39163ca147c42e159 Mon Sep 17 00:00:00 2001
From: Sam Doran <sdoran@redhat.com>
Date: Mon, 8 Oct 2018 15:13:52 -0400
Subject: [PATCH] Add documentation on underlying tools in user module (#46455)
 (#46511)

(cherry picked from commit bcfdc37be021695d593576fa205b6698acceb398)
---
 changelogs/fragments/user-docs-underlying-tools.yaml | 2 ++
 lib/ansible/modules/system/user.py                   | 9 +++++++++
 2 files changed, 11 insertions(+)
 create mode 100644 changelogs/fragments/user-docs-underlying-tools.yaml

diff --git a/changelogs/fragments/user-docs-underlying-tools.yaml b/changelogs/fragments/user-docs-underlying-tools.yaml
new file mode 100644
index 00000000000..2424d7224cb
--- /dev/null
+++ b/changelogs/fragments/user-docs-underlying-tools.yaml
@@ -0,0 +1,2 @@
+bugfixes:
+  - user - add documentation on what underlying tools are used on each platform (https://github.com/ansible/ansible/issues/44266)
diff --git a/lib/ansible/modules/system/user.py b/lib/ansible/modules/system/user.py
index b5817d75ff1..1bb6b442f71 100644
--- a/lib/ansible/modules/system/user.py
+++ b/lib/ansible/modules/system/user.py
@@ -24,6 +24,13 @@ notes:
   - For Windows targets, use the M(win_user) module instead.
   - On SunOS platforms, the shadow file is backed up automatically since this module edits it directly.
     On other platforms, the shadow file is backed up by the underlying tools used by this module.
+  - On macOS, this module uses C(dscl) to create, modify, and delete accounts. C(dseditgroup) is used to
+    modify group membership. Accounts are hidden from the login window by modifying
+    C(/Library/Preferences/com.apple.loginwindow.plist).
+  - On FreeBSD, this module uses C(pw useradd) and C(chpass) to create, C(pw usermod) and C(chpass) to modify,
+    C(pw userdel) remove, C(pw lock) to lock, and C(pw unlock) to unlock accounts.
+  - On all other platforms, this module uses C(useradd) to create, C(usermod) to modify, and
+    C(userdel) to remove accounts.
 description:
     - Manage user accounts and user attributes.
     - For Windows targets, use the M(win_user) module instead.
@@ -78,6 +85,8 @@ options:
             - Optionally set the user's shell.
             - On macOS, before version 2.5, the default shell for non-system users was /usr/bin/false.
               Since 2.5, the default shell for non-system users on macOS is /bin/bash.
+            - On other operating systems, the default shell is determined by the underlying tool being
+              used. See Notes for details.
     home:
         description:
             - Optionally set the user's home directory.