postgresql_user: improve documentation (#872)

* postgresql_user: improve documentation

* fix

* Update plugins/modules/database/postgresql/postgresql_user.py

Co-authored-by: Sandra McCann <samccann@redhat.com>

* Update plugins/modules/database/postgresql/postgresql_user.py

Co-authored-by: Sandra McCann <samccann@redhat.com>

* Update plugins/modules/database/postgresql/postgresql_user.py

Co-authored-by: Sandra McCann <samccann@redhat.com>

* add suggested

* fix

* misc fix

Co-authored-by: Sandra McCann <samccann@redhat.com>

plugins/modules/database/postgresql/postgresql_user.py

@@ -10,23 +10,17 @@ __metaclass__ = type
 DOCUMENTATION = r'''
 ---
 module: postgresql_user
-short_description: Add or remove a user (role) from a PostgreSQL server instance
+short_description: Create, alter, or remove a user (role) from a PostgreSQL server instance
 description:
-- Adds or removes a user (role) from a PostgreSQL server instance
+- Creates, alters, or removes a user (role) from a PostgreSQL server instance
   ("cluster" in PostgreSQL terminology) and, optionally,
   grants the user access to an existing database or tables.
 - A user is a role with login privilege.
-- The fundamental function of the module is to create, or delete, users from
+- You can also use it to grant or revoke user's privileges in a particular database.
-  a PostgreSQL instances. Privilege assignment, or removal, is an optional
+- You cannot remove a user while it still has any privileges granted to it in any database.
-  step, which works on one database at a time. This allows for the module to
+- Set I(fail_on_user) to C(no) to make the module ignore failures when trying to remove a user.
-  be called several times in the same module to modify the permissions on
+  In this case, the module reports if changes happened as usual and separately reports
-  different databases, or to grant permissions to already existing users.
+  whether the user has been removed or not.
-- A user cannot be removed until all the privileges have been stripped from
-  the user. In such situation, if the module tries to remove the user it
-  will fail. To avoid this from happening the fail_on_user option signals
-  the module to try to remove the user, but if not possible keep going; the
-  module will report if changes happened and separately if the user was
-  removed or not.
 options:
   name:
     description:
@@ -39,33 +33,33 @@ options:
     description:
     - Set the user's password, before 1.4 this was required.
     - Password can be passed unhashed or hashed (MD5-hashed).
-    - Unhashed password will automatically be hashed when saved into the
+    - An unhashed password is automatically hashed when saved into the
-      database if C(encrypted) parameter is set, otherwise it will be save in
+      database if I(encrypted) is set, otherwise it is saved in
       plain text format.
-    - When passing an MD5-hashed password it must be generated with the format
+    - When passing an MD5-hashed password, you must generate it with the format
       C('str["md5"] + md5[ password + username ]'), resulting in a total of
       35 characters. An easy way to do this is C(echo "md5$(echo -n
       'verysecretpasswordJOE' | md5sum | awk '{print $1}')").
     - Note that if the provided password string is already in MD5-hashed
-      format, then it is used as-is, regardless of C(encrypted) parameter.
+      format, then it is used as-is, regardless of I(encrypted) option.
     type: str
   db:
     description:
-    - Name of database to connect to and where user's permissions will be granted.
+    - Name of database to connect to and where user's permissions are granted.
     type: str
     aliases:
     - login_db
   fail_on_user:
     description:
-    - If C(yes), fail when user (role) can't be removed. Otherwise just log and continue.
+    - If C(yes), fails when the user (role) cannot be removed. Otherwise just log and continue.
-    default: 'yes'
+    default: yes
     type: bool
     aliases:
     - fail_on_role
   priv:
     description:
     - "Slash-separated PostgreSQL privileges string: C(priv1/priv2), where
-      privileges can be defined for database ( allowed options - 'CREATE',
+      you can define the user's privileges for the database ( allowed options - 'CREATE',
       'CONNECT', 'TEMPORARY', 'TEMP', 'ALL'. For example C(CONNECT) ) or
       for table ( allowed options - 'SELECT', 'INSERT', 'UPDATE', 'DELETE',
       'TRUNCATE', 'REFERENCES', 'TRIGGER', 'ALL'. For example
@@ -82,9 +76,10 @@ options:
                '[NO]INHERIT', '[NO]LOGIN', '[NO]REPLICATION', '[NO]BYPASSRLS' ]
   session_role:
     description:
-    - Switch to session_role after connecting.
+    - Switch to session role after connecting.
-    - The specified session_role must be a role that the current login_user is a member of.
+    - The specified session role must be a role that the current login_user is a member of.
-    - Permissions checking for SQL commands is carried out as though the session_role were the one that had logged in originally.
+    - Permissions checking for SQL commands is carried out as though the session role
+      were the one that had logged in originally.
     type: str
   state:
     description:
@@ -95,24 +90,26 @@ options:
   encrypted:
     description:
     - Whether the password is stored hashed in the database.
-    - Passwords can be passed already hashed or unhashed, and postgresql
+    - You can specify an unhashed password, and PostgreSQL ensures
-      ensures the stored password is hashed when C(encrypted) is set.
+      the stored password is hashed when I(encrypted=yes) is set.
-    - "Note: Postgresql 10 and newer doesn't support unhashed passwords."
+      If you specify a hashed password, the module uses it as-is,
+      regardless of the setting of I(encrypted).
+    - "Note: Postgresql 10 and newer does not support unhashed passwords."
     - Previous to Ansible 2.6, this was C(no) by default.
-    default: 'yes'
+    default: yes
     type: bool
   expires:
     description:
     - The date at which the user's password is to expire.
-    - If set to C('infinity'), user's password never expire.
+    - If set to C('infinity'), user's password never expires.
-    - Note that this value should be a valid SQL date and time type.
+    - Note that this value must be a valid SQL date and time type.
     type: str
   no_password_changes:
     description:
-    - If C(yes), don't inspect database for password changes. Effective when
+    - If C(yes), does not inspect the database for password changes.
-      C(pg_authid) is not accessible (such as AWS RDS). Otherwise, make
+      Useful when C(pg_authid) is not accessible (such as in AWS RDS).
-      password changes as necessary.
+      Otherwise, makes password changes as necessary.
-    default: 'no'
+    default: no
     type: bool
   conn_limit:
     description:
@@ -120,7 +117,7 @@ options:
     type: int
   ssl_mode:
     description:
-      - Determines whether or with what priority a secure SSL TCP/IP connection will be negotiated with the server.
+      - Determines how an SSL session is negotiated with the server.
       - See U(https://www.postgresql.org/docs/current/static/libpq-ssl.html) for more information on the modes.
       - Default of C(prefer) matches libpq default.
     type: str
@@ -129,36 +126,37 @@ options:
   ca_cert:
     description:
       - Specifies the name of a file containing SSL certificate authority (CA) certificate(s).
-      - If the file exists, the server's certificate will be verified to be signed by one of these authorities.
+      - If the file exists, verifies that the server's certificate is signed by one of these authorities.
     type: str
     aliases: [ ssl_rootcert ]
   groups:
     description:
-    - The list of groups (roles) that need to be granted to the user.
+    - The list of groups (roles) that you want to grant to the user.
     type: list
     elements: str
   comment:
     description:
-    - Add a comment on the user (equal to the COMMENT ON ROLE statement result).
+    - Adds a comment on the user (equivalent to the C(COMMENT ON ROLE) statement).
     type: str
     version_added: '0.2.0'
   trust_input:
     description:
-    - If C(no), check whether values of parameters I(name), I(password), I(privs), I(expires),
+    - If C(no), checks whether values of options I(name), I(password), I(privs), I(expires),
       I(role_attr_flags), I(groups), I(comment), I(session_role) are potentially dangerous.
-    - It makes sense to use C(yes) only when SQL injections via the parameters are possible.
+    - It makes sense to use C(yes) only when SQL injections through the options are possible.
     type: bool
     default: yes
     version_added: '0.2.0'
 notes:
 - The module creates a user (role) with login privilege by default.
-  Use NOLOGIN role_attr_flags to change this behaviour.
+  Use C(NOLOGIN) I(role_attr_flags) to change this behaviour.
-- If you specify PUBLIC as the user (role), then the privilege changes will apply to all users (roles).
+- If you specify C(PUBLIC) as the user (role), then the privilege changes apply to all users (roles).
-  You may not specify password or role_attr_flags when the PUBLIC user is specified.
+  You may not specify password or role_attr_flags when the C(PUBLIC) user is specified.
 - SCRAM-SHA-256-hashed passwords (SASL Authentication) require PostgreSQL version 10 or newer.
   On the previous versions the whole hashed string is used as a password.
 - 'Working with SCRAM-SHA-256-hashed passwords, be sure you use the I(environment:) variable
   C(PGOPTIONS: "-c password_encryption=scram-sha-256") (see the provided example).'
+- Supports ``check_mode``.
 seealso:
 - module: community.general.postgresql_privs
 - module: community.general.postgresql_membership