Update documentation of pamd module (#24712)

Updated explanation and documentation of new_module*
in pamd documentation

Fixes #24516

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>

lib/ansible/modules/system/pamd.py

@@ -56,19 +56,15 @@ options:
       - The module path of the PAM rule being modified.  The type,
         control and module_path all must match a rule to be modified.
   new_type:
-    required: false
     description:
-    - The type to assign to the new rule.
+    - The new type to assign to the new rule.
   new_control:
-    required: false
     description:
-    - The control to assign to the new rule.
+    - The new control to assign to the new rule.
   new_module_path:
-    required: false
     description:
-    - The control to assign to the new rule.
+    - The new module path to be assigned to the new rule.
   module_arguments:
-    required: false
     description:
     - When state is 'updated', the module_arguments will replace existing
       module_arguments.  When state is 'args_absent' args matching those
@@ -78,7 +74,6 @@ options:
       takes a value denoted by '=', the value will be changed to that specified
       in module_arguments.
   state:
-    required: false
     default: updated
     choices:
     - updated
@@ -96,7 +91,6 @@ options:
       must all be specified.  If state is 'args_absent' or 'args_present',
       new_type, new_control, and new_module_path will be ignored.
   path:
-    required: false
     default: /etc/pam.d/
     description:
     - This is the path to the PAM service files
@@ -130,15 +124,16 @@ EXAMPLES = """
     new_module_path: pam_faillock.so
     state: before
 
-- name: Insert a new rule after an existing rule
+- name: Insert a new rule pam_wheel.so with argument 'use_uid' after an existing rule pam_rootok.so
   pamd:
-    name: system-auth
+    name: su
     type: auth
-    control: required
-    module_path: pam_faillock.so
+    control: sufficient
+    module_path: pam_rootok.so
     new_type: auth
-    new_control: sufficient
-    new_module_path: pam_faillock.so
+    new_control: required
+    new_module_path: pam_wheel.so
+    module_arguments: 'use_uid'
     state: after
 
 - name: Remove module arguments from an existing rule

test/sanity/pep8/legacy-files.txt

@@ -550,7 +550,6 @@ lib/ansible/modules/system/open_iscsi.py
 lib/ansible/modules/system/openwrt_init.py
 lib/ansible/modules/system/osx_defaults.py
 lib/ansible/modules/system/pam_limits.py
-lib/ansible/modules/system/pamd.py
 lib/ansible/modules/system/puppet.py
 lib/ansible/modules/system/runit.py
 lib/ansible/modules/system/seboolean.py