include review comments 2

changelogs/fragments/4849-add-password-prompt-support-for-machinectl.yml

@@ -1,2 +1,2 @@
 minor_changes:
-  - machinectl become method can now be used with a password from a none root user, if a polkit rule is present.
+  - machinectl become plugin - can now be used with a password from another user than root, if a polkit rule is present (https://github.com/ansible-collections/community.general/pull/4849).

plugins/become/machinectl.py

@@ -67,13 +67,16 @@
               - section: machinectl_become_plugin
                 key: password
     notes:
-      - This plugin only works correctly with a polkit rule which will alter the behaviour of machinectl. This rule must
-        alter the prompt behaviour to ask directly for the user credentials, if the user is allowed to perform the
-        action (take a look at the examples section). If such a rule is not present the plugin only work if it is used
-        in context with the root user, because then no further prompt will be shown by machinectl.
+      - When not using this plugin with user C(root), it only works correctly with a polkit rule which will alter
+        the behaviour of machinectl. This rule must alter the prompt behaviour to ask directly for the user credentials,
+        if the user is allowed to perform the action (take a look at the examples section).
+        If such a rule is not present the plugin only work if it is used in context with the root user,
+        because then no further prompt will be shown by machinectl.
 '''
 
 EXAMPLES = r'''
+# A polkit rule needed to use the module with a non-root user.
+# See the Notes section for details.
 60-machinectl-fast-user-auth.rules: |
     polkit.addRule(function(action, subject) {
         if(action.id == "org.freedesktop.machine1.host-shell" && subject.isInGroup("wheel")) {