Documentation: fix formatting (#73186)

10 files changed, 110 insertions, 106 deletions

diff --git a/lib/ansible/modules/command.py b/lib/ansible/modules/command.py
index dcecbe646f..1680543295 100644
--- a/lib/ansible/modules/command.py
+++ b/lib/ansible/modules/command.py
@@ -45,7 +45,7 @@ options:
   creates:
     type: path
     description:
-      - A filename or (since 2.0) glob pattern. If a matching file already exists, this step B(won't) be run.
+      - A filename or (since 2.0) glob pattern. If a matching file already exists, this step B(will not) be run.
   removes:
     type: path
     description:
@@ -79,11 +79,12 @@ options:
     type: bool
     default: yes
 notes:
-    -  If you want to run a command through the shell (say you are using C(<), C(>), C(|), etc), you actually want the M(ansible.builtin.shell) module instead.
+    -  If you want to run a command through the shell (say you are using C(<), C(>), C(|), and so on),
+       you actually want the M(ansible.builtin.shell) module instead.
        Parsing shell metacharacters can lead to unexpected commands being executed if quoting is not done correctly so it is more secure to
        use the C(command) module when possible.
-    -  " C(creates), C(removes), and C(chdir) can be specified after the command.
-       For instance, if you only want to run a command if a certain file does not exist, use this."
+    -  C(creates), C(removes), and C(chdir) can be specified after the command.
+       For instance, if you only want to run a command if a certain file does not exist, use this.
     -  Check mode is supported when passing C(creates) or C(removes). If running in check mode and either of these are specified, the module will
        check for the existence of the file and report the correct changed status. If these are not supplied, the task will be skipped.
     -  The C(executable) parameter is removed since version 2.4. If you have a need for this parameter, use the M(ansible.builtin.shell) module instead.
@@ -101,28 +102,28 @@ author:
 
 EXAMPLES = r'''
 - name: Return motd to registered var
-  command: cat /etc/motd
+  ansible.builtin.command: cat /etc/motd
   register: mymotd
 
 # free-form (string) arguments, all arguments on one line
 - name: Run command if /path/to/database does not exist (without 'args')
-  command: /usr/bin/make_database.sh db_user db_name creates=/path/to/database
+  ansible.builtin.command: /usr/bin/make_database.sh db_user db_name creates=/path/to/database
 
 # free-form (string) arguments, some arguments on separate lines with the 'args' keyword
 # 'args' is a task keyword, passed at the same level as the module
 - name: Run command if /path/to/database does not exist (with 'args' keyword)
-  command: /usr/bin/make_database.sh db_user db_name
+  ansible.builtin.command: /usr/bin/make_database.sh db_user db_name
   args:
     creates: /path/to/database
 
 # 'cmd' is module parameter
 - name: Run command if /path/to/database does not exist (with 'cmd' parameter)
-  command:
+  ansible.builtin.command:
     cmd: /usr/bin/make_database.sh db_user db_name
     creates: /path/to/database
 
 - name: Change the working directory to somedir/ and run the command as db_owner if /path/to/database does not exist
-  command: /usr/bin/make_database.sh db_user db_name
+  ansible.builtin.command: /usr/bin/make_database.sh db_user db_name
   become: yes
   become_user: db_owner
   args:
@@ -132,7 +133,7 @@ EXAMPLES = r'''
 # argv (list) arguments, each argument on a separate line, 'args' keyword not necessary
 # 'argv' is a parameter, indented one level from the module
 - name: Use 'argv' to send a command as a list - leave 'command' empty
-  command:
+  ansible.builtin.command:
     argv:
       - /usr/bin/make_database.sh
       - Username with whitespace
@@ -140,7 +141,7 @@ EXAMPLES = r'''
     creates: /path/to/database
 
 - name: Safely use templated variable to run command. Always use the quote filter to avoid injection issues
-  command: cat {{ myfile|quote }}
+  ansible.builtin.command: cat {{ myfile|quote }}
   register: myoutput
 '''
 
@@ -151,49 +152,49 @@ msg:
   type: bool
   sample: True
 start:
-  description: The command execution start time
+  description: The command execution start time.
   returned: always
   type: str
   sample: '2017-09-29 22:03:48.083128'
 end:
-  description: The command execution end time
+  description: The command execution end time.
   returned: always
   type: str
   sample: '2017-09-29 22:03:48.084657'
 delta:
-  description: The command execution delta time
+  description: The command execution delta time.
   returned: always
   type: str
   sample: '0:00:00.001529'
 stdout:
-  description: The command standard output
+  description: The command standard output.
   returned: always
   type: str
   sample: 'Clustering node rabbit@slave1 with rabbit@master …'
 stderr:
-  description: The command standard error
+  description: The command standard error.
   returned: always
   type: str
   sample: 'ls cannot access foo: No such file or directory'
 cmd:
-  description: The command executed by the task
+  description: The command executed by the task.
   returned: always
   type: list
   sample:
   - echo
   - hello
 rc:
-  description: The command return code (0 means success)
+  description: The command return code (0 means success).
   returned: always
   type: int
   sample: 0
 stdout_lines:
-  description: The command standard output split in lines
+  description: The command standard output split in lines.
   returned: always
   type: list
   sample: [u'Clustering node rabbit@slave1 with rabbit@master …']
 stderr_lines:
-  description: The command standard error split in lines
+  description: The command standard error split in lines.
   returned: always
   type: list
   sample: [u'ls cannot access foo: No such file or directory', u'ls …']
diff --git a/lib/ansible/modules/debug.py b/lib/ansible/modules/debug.py
index 86c4b95174..c98bcc5702 100644
--- a/lib/ansible/modules/debug.py
+++ b/lib/ansible/modules/debug.py
@@ -34,7 +34,7 @@ options:
     type: str
   verbosity:
     description:
-    - A number that controls when the debug is run, if you set to 3 it will only run debug when -vvv or above
+    - A number that controls when the debug is run, if you set to 3 it will only run debug when -vvv or above.
     type: int
     default: 0
     version_added: '2.1'
diff --git a/lib/ansible/modules/expect.py b/lib/ansible/modules/expect.py
index 0f2621566f..3bb9d9608e 100644
--- a/lib/ansible/modules/expect.py
+++ b/lib/ansible/modules/expect.py
@@ -12,7 +12,7 @@ DOCUMENTATION = r'''
 ---
 module: expect
 version_added: '2.0'
-short_description: Executes a command and responds to prompts.
+short_description: Executes a command and responds to prompts
 description:
      - The C(expect) module executes a command and responds to prompts.
      - The given command will be executed on all selected nodes. It will not be
@@ -58,7 +58,7 @@ requirements:
   - pexpect >= 3.3
 notes:
   - If you want to run a command through the shell (say you are using C(<),
-    C(>), C(|), etc), you must specify a shell in the command such as
+    C(>), C(|), and so on), you must specify a shell in the command such as
     C(/bin/bash -c "/path/to/something | grep else").
   - The question, or key, under I(responses) is a python regex match. Case
     insensitive searches are indicated with a prefix of C(?i).
@@ -68,7 +68,7 @@ notes:
     the response. The list functionality is new in 2.1.
   - The M(ansible.builtin.expect) module is designed for simple scenarios.
     For more complex needs, consider the use of expect code with the M(ansible.builtin.shell)
-    or M(ansible.builtin.script) modules. (An example is part of the M(ansible.builtin.shell) module documentation)
+    or M(ansible.builtin.script) modules. (An example is part of the M(ansible.builtin.shell) module documentation).
 seealso:
 - module: ansible.builtin.script
 - module: ansible.builtin.shell
@@ -77,7 +77,7 @@ author: "Matt Martz (@sivel)"
 
 EXAMPLES = r'''
 - name: Case insensitive password string match
-  expect:
+  ansible.builtin.expect:
     command: passwd username
     responses:
       (?i)password: "MySekretPa$$word"
@@ -85,7 +85,7 @@ EXAMPLES = r'''
   no_log: true
 
 - name: Generic question with multiple different responses
-  expect:
+  ansible.builtin.expect:
     command: /path/to/custom/command
     responses:
       Question:
diff --git a/lib/ansible/modules/git.py b/lib/ansible/modules/git.py
index b47e94517b..8f432fd07c 100644
--- a/lib/ansible/modules/git.py
+++ b/lib/ansible/modules/git.py
@@ -33,12 +33,12 @@ options:
         description:
             - What version of the repository to check out.  This can be
               the literal string C(HEAD), a branch name, a tag name.
-              It can also be a I(SHA-1) hash, in which case C(refspec) needs
+              It can also be a I(SHA-1) hash, in which case I(refspec) needs
               to be specified if the given revision is not already available.
         default: "HEAD"
     accept_hostkey:
         description:
-            - if C(yes), ensure that "-o StrictHostKeyChecking=no" is
+            - If C(yes), ensure that "-o StrictHostKeyChecking=no" is
               present as an ssh option.
         type: bool
         default: 'no'
@@ -57,7 +57,7 @@ options:
         version_added: "1.5"
     reference:
         description:
-            - Reference repository (see "git clone --reference ...")
+            - Reference repository (see "git clone --reference ...").
         version_added: "1.4"
     remote:
         description:
@@ -77,7 +77,7 @@ options:
             - If C(yes), any modified files in the working
               repository will be discarded.  Prior to 0.7, this was always
               'yes' and could not be disabled.  Prior to 1.9, the default was
-              `yes`
+              `yes`.
         type: bool
         default: 'no'
         version_added: "0.7"
@@ -89,13 +89,13 @@ options:
         version_added: "1.2"
     clone:
         description:
-            - If C(no), do not clone the repository even if it does not exist locally
+            - If C(no), do not clone the repository even if it does not exist locally.
         type: bool
         default: 'yes'
         version_added: "1.9"
     update:
         description:
-            - If C(no), do not retrieve new revisions from the origin repository
+            - If C(no), do not retrieve new revisions from the origin repository.
             - Operations like archive will work on the existing (old) repository and might
               not respond to changes to the options version or remote.
         type: bool
@@ -108,7 +108,7 @@ options:
         version_added: "1.4"
     bare:
         description:
-            - if C(yes), repository will be created as a bare repo, otherwise
+            - If C(yes), repository will be created as a bare repo, otherwise
               it will be a standard repo with a workspace.
         type: bool
         default: 'no'
@@ -121,7 +121,7 @@ options:
 
     recursive:
         description:
-            - if C(no), repository will be cloned without the --recursive
+            - If C(no), repository will be cloned without the --recursive
               option, skipping sub-modules.
         type: bool
         default: 'yes'
@@ -129,7 +129,7 @@ options:
 
     track_submodules:
         description:
-            - if C(yes), submodules will track the latest commit on their
+            - If C(yes), submodules will track the latest commit on their
               master branch (or other branch specified in .gitmodules).  If
               C(no), submodules will be kept at the revision specified by the
               main project. This is equivalent to specifying the --remote flag
@@ -140,8 +140,8 @@ options:
 
     verify_commit:
         description:
-            - if C(yes), when cloning or checking out a C(version) verify the
-              signature of a GPG signed commit. This requires C(git) version>=2.1.0
+            - If C(yes), when cloning or checking out a I(version) verify the
+              signature of a GPG signed commit. This requires git version>=2.1.0
               to be installed. The commit MUST be signed and the public key MUST
               be present in the GPG keyring.
         type: bool
@@ -153,14 +153,14 @@ options:
             - Specify archive file path with extension. If specified, creates an
               archive file of the specified format containing the tree structure
               for the source tree.
-              Allowed archive formats ["zip", "tar.gz", "tar", "tgz"]
+              Allowed archive formats ["zip", "tar.gz", "tar", "tgz"].
             - This will clone and perform git archive from local directory as not
               all git servers support git archive.
         version_added: "2.4"
 
     archive_prefix:
         description:
-            - Specify a prefix to add to each file path in archive. Requires C(archive) to be specified.
+            - Specify a prefix to add to each file path in archive. Requires I(archive) to be specified.
         version_added: "2.10"
         type: str
 
@@ -188,47 +188,48 @@ notes:
       one solution is to use the option accept_hostkey. Another solution is to
       add the remote host public key in C(/etc/ssh/ssh_known_hosts) before calling
       the git module, with the following command: ssh-keyscan -H remote_host.com >> /etc/ssh/ssh_known_hosts."
+    - Supports C(check_mode).
 '''
 
 EXAMPLES = '''
 - name: Git checkout
-  git:
+  ansible.builtin.git:
     repo: 'https://foosball.example.org/path/to/repo.git'
     dest: /srv/checkout
     version: release-0.22
 
 - name: Read-write git checkout from github
-  git:
+  ansible.builtin.git:
     repo: git@github.com:mylogin/hello.git
     dest: /home/mylogin/hello
 
 - name: Just ensuring the repo checkout exists
-  git:
+  ansible.builtin.git:
     repo: 'https://foosball.example.org/path/to/repo.git'
     dest: /srv/checkout
     update: no
 
 - name: Just get information about the repository whether or not it has already been cloned locally
-  git:
+  ansible.builtin.git:
     repo: 'https://foosball.example.org/path/to/repo.git'
     dest: /srv/checkout
     clone: no
     update: no
 
 - name: Checkout a github repo and use refspec to fetch all pull requests
-  git:
+  ansible.builtin.git:
     repo: https://github.com/ansible/ansible-examples.git
     dest: /src/ansible-examples
     refspec: '+refs/pull/*:refs/heads/*'
 
 - name: Create git archive from repo
-  git:
+  ansible.builtin.git:
     repo: https://github.com/ansible/ansible-examples.git
     dest: /src/ansible-examples
     archive: /tmp/ansible-examples.zip
 
 - name: Clone a repo with separate git directory
-  git:
+  ansible.builtin.git:
     repo: https://github.com/ansible/ansible-examples.git
     dest: /src/ansible-examples
     separate_git_dir: /src/ansible-examples.git
@@ -236,12 +237,12 @@ EXAMPLES = '''
 
 RETURN = '''
 after:
-    description: last commit revision of the repository retrieved during the update
+    description: Last commit revision of the repository retrieved during the update.
     returned: success
     type: str
     sample: 4c020102a9cd6fe908c9a4a326a38f972f63a903
 before:
-    description: commit revision before the repository was updated, "null" for new repository
+    description: Commit revision before the repository was updated, "null" for new repository.
     returned: success
     type: str
     sample: 67c04ebe40a003bda0efb34eacfb93b0cafdf628
@@ -256,12 +257,12 @@ warnings:
     type: str
     sample: Your git version is too old to fully support the depth argument. Falling back to full checkouts.
 git_dir_now:
-    description: Contains the new path of .git directory if it's changed
+    description: Contains the new path of .git directory if it is changed.
     returned: success
     type: str
     sample: /path/to/new/git/dir
 git_dir_before:
-    description: Contains the original path of .git directory if it's changed
+    description: Contains the original path of .git directory if it is changed.
     returned: success
     type: str
     sample: /path/to/old/git/dir
diff --git a/lib/ansible/modules/group.py b/lib/ansible/modules/group.py
index 1deb967afe..297e25796d 100644
--- a/lib/ansible/modules/group.py
+++ b/lib/ansible/modules/group.py
@@ -45,7 +45,7 @@ options:
         description:
             - Forces the use of "local" command alternatives on platforms that implement it.
             - This is useful in environments that use centralized authentication when you want to manipulate the local groups.
-              (e.g. it uses C(lgroupadd) instead of C(groupadd)).
+              (for example, it uses C(lgroupadd) instead of C(groupadd)).
             - This requires that these commands exist on the targeted host, otherwise it will be a fatal error.
         type: bool
         default: no
diff --git a/lib/ansible/modules/group_by.py b/lib/ansible/modules/group_by.py
index 4a709d287e..34290d02b7 100644
--- a/lib/ansible/modules/group_by.py
+++ b/lib/ansible/modules/group_by.py
@@ -39,20 +39,20 @@ author:
 
 EXAMPLES = r'''
 - name: Create groups based on the machine architecture
-  group_by:
+  ansible.builtin.group_by:
     key: machine_{{ ansible_machine }}
 
 - name: Create groups like 'virt_kvm_host'
-  group_by:
+  ansible.builtin.group_by:
     key: virt_{{ ansible_virtualization_type }}_{{ ansible_virtualization_role }}
 
 - name: Create nested groups
-  group_by:
+  ansible.builtin.group_by:
     key: el{{ ansible_distribution_major_version }}-{{ ansible_architecture }}
     parents:
       - el{{ ansible_distribution_major_version }}
 
-# Add all active hosts to a static group
-- group_by:
+- name: Add all active hosts to a static group
+  ansible.builtin.group_by:
     key: done
 '''
diff --git a/lib/ansible/modules/hostname.py b/lib/ansible/modules/hostname.py
index c0ffe37adf..ab99045a58 100644
--- a/lib/ansible/modules/hostname.py
+++ b/lib/ansible/modules/hostname.py
@@ -36,7 +36,7 @@ options:
 
 EXAMPLES = '''
 - name: Set a hostname
-  hostname:
+  ansible.builtin.hostname:
     name: web01
 '''
 
diff --git a/lib/ansible/modules/package.py b/lib/ansible/modules/package.py
index a99dab1d6b..f15ad5af8e 100644
--- a/lib/ansible/modules/package.py
+++ b/lib/ansible/modules/package.py
@@ -33,9 +33,8 @@ options:
     required: true
   use:
     description:
-      - The required package manager module to use (yum, apt, etc). The default 'auto' will use existing facts or try to autodetect it.
+      - The required package manager module to use (`yum`, `apt`, and so on). The default 'auto' will use existing facts or try to autodetect it.
       - You should only use this field if the automatic selection is not working for some reason.
-    required: false
     default: auto
 requirements:
     - Whatever is required for the package plugins specific for each system.
@@ -45,18 +44,18 @@ notes:
 '''
 EXAMPLES = '''
 - name: Install ntpdate
-  package:
+  ansible.builtin.package:
     name: ntpdate
     state: present
 
 # This uses a variable as this changes per distribution.
 - name: Remove the apache package
-  package:
+  ansible.builtin.package:
     name: "{{ apache }}"
     state: absent
 
 - name: Install the latest version of Apache and MariaDB
-  package:
+  ansible.builtin.package:
     name:
       - httpd
       - mariadb-server
diff --git a/lib/ansible/modules/package_facts.py b/lib/ansible/modules/package_facts.py
index ed314b4a29..97bfd6f0c1 100644
--- a/lib/ansible/modules/package_facts.py
+++ b/lib/ansible/modules/package_facts.py
@@ -10,9 +10,9 @@ __metaclass__ = type
 
 DOCUMENTATION = '''
 module: package_facts
-short_description: package information as facts
+short_description: Package information as facts
 description:
-  - Return information about installed packages as facts
+  - Return information about installed packages as facts.
 options:
   manager:
     description:
@@ -39,19 +39,21 @@ author:
   - Matthew Jones (@matburt)
   - Brian Coca (@bcoca)
   - Adam Miller (@maxamillion)
+notes:
+  - Supports C(check_mode).
 '''
 
 EXAMPLES = '''
 - name: Gather the package facts
-  package_facts:
+  ansible.builtin.package_facts:
     manager: auto
 
 - name: Print the package facts
-  debug:
+  ansible.builtin.debug:
     var: ansible_facts.packages
 
 - name: Check whether a package called foobar is installed
-  debug:
+  ansible.builtin.debug:
     msg: "{{ ansible_facts.packages['foobar'] | length }} versions of foobar are installed!"
   when: "'foobar' in ansible_facts.packages"
 
@@ -59,7 +61,7 @@ EXAMPLES = '''
 
 RETURN = '''
 ansible_facts:
-  description: facts to add to ansible_facts
+  description: Facts to add to ansible_facts.
   returned: always
   type: complex
   contains:
diff --git a/lib/ansible/modules/user.py b/lib/ansible/modules/user.py
index 0e37cbf531..583dfe22fc 100644
--- a/lib/ansible/modules/user.py
+++ b/lib/ansible/modules/user.py
@@ -203,7 +203,7 @@ options:
         description:
             - Forces the use of "local" command alternatives on platforms that implement it.
             - This is useful in environments that use centralized authentication when you want to manipulate the local users
-              (i.e. it uses C(luseradd) instead of C(useradd)).
+              (in other words, it uses C(luseradd) instead of C(useradd)).
             - This will check C(/etc/passwd) for an existing account before invoking commands. If the local account database
               exists somewhere other than C(/etc/passwd), this setting will not work properly.
             - This requires that the above commands as well as C(/etc/passwd) must exist on the target host, otherwise it will be a fatal error.
@@ -250,6 +250,7 @@ notes:
     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.
+  - Supports C(check_mode).
 seealso:
 - module: ansible.posix.authorized_key
 - module: ansible.builtin.group
@@ -260,64 +261,64 @@ author:
 
 EXAMPLES = r'''
 - name: Add the user 'johnd' with a specific uid and a primary group of 'admin'
-  user:
+  ansible.builtin.user:
     name: johnd
     comment: John Doe
     uid: 1040
     group: admin
 
 - name: Add the user 'james' with a bash shell, appending the group 'admins' and 'developers' to the user's groups
-  user:
+  ansible.builtin.user:
     name: james
     shell: /bin/bash
     groups: admins,developers
     append: yes
 
 - name: Remove the user 'johnd'
-  user:
+  ansible.builtin.user:
     name: johnd
     state: absent
     remove: yes
 
 - name: Create a 2048-bit SSH key for user jsmith in ~jsmith/.ssh/id_rsa
-  user:
+  ansible.builtin.user:
     name: jsmith
     generate_ssh_key: yes
     ssh_key_bits: 2048
     ssh_key_file: .ssh/id_rsa
 
 - name: Added a consultant whose account you want to expire
-  user:
+  ansible.builtin.user:
     name: james18
     shell: /bin/zsh
     groups: developers
     expires: 1422403387
 
 - name: Starting at Ansible 2.6, modify user, remove expiry time
-  user:
+  ansible.builtin.user:
     name: james18
     expires: -1
 '''
 
 RETURN = r'''
 append:
-  description: Whether or not to append the user to groups
-  returned: When state is 'present' and the user exists
+  description: Whether or not to append the user to groups.
+  returned: When state is C(present) and the user exists
   type: bool
   sample: True
 comment:
-  description: Comment section from passwd file, usually the user name
+  description: Comment section from passwd file, usually the user name.
   returned: When user exists
   type: str
   sample: Agent Smith
 create_home:
-  description: Whether or not to create the home directory
+  description: Whether or not to create the home directory.
   returned: When user does not exist and not check mode
   type: bool
   sample: True
 force:
-  description: Whether or not a user account was forcibly deleted
-  returned: When state is 'absent' and user exists
+  description: Whether or not a user account was forcibly deleted.
+  returned: When I(state) is C(absent) and user exists
   type: bool
   sample: False
 group:
@@ -326,76 +327,76 @@ group:
   type: int
   sample: 1001
 groups:
-  description: List of groups of which the user is a member
-  returned: When C(groups) is not empty and C(state) is 'present'
+  description: List of groups of which the user is a member.
+  returned: When I(groups) is not empty and I(state) is C(present)
   type: str
   sample: 'chrony,apache'
 home:
-  description: "Path to user's home directory"
-  returned: When C(state) is 'present'
+  description: "Path to user's home directory."
+  returned: When I(state) is C(present)
   type: str
   sample: '/home/asmith'
 move_home:
-  description: Whether or not to move an existing home directory
-  returned: When C(state) is 'present' and user exists
+  description: Whether or not to move an existing home directory.
+  returned: When I(state) is C(present) and user exists
   type: bool
   sample: False
 name:
-  description: User account name
+  description: User account name.
   returned: always
   type: str
   sample: asmith
 password:
-  description: Masked value of the password
-  returned: When C(state) is 'present' and C(password) is not empty
+  description: Masked value of the password.
+  returned: When I(state) is C(present) and I(password) is not empty
   type: str
   sample: 'NOT_LOGGING_PASSWORD'
 remove:
-  description: Whether or not to remove the user account
-  returned: When C(state) is 'absent' and user exists
+  description: Whether or not to remove the user account.
+  returned: When I(state) is C(absent) and user exists
   type: bool
   sample: True
 shell:
-  description: User login shell
-  returned: When C(state) is 'present'
+  description: User login shell.
+  returned: When I(state) is C(present)
   type: str
   sample: '/bin/bash'
 ssh_fingerprint:
-  description: Fingerprint of generated SSH key
-  returned: When C(generate_ssh_key) is C(True)
+  description: Fingerprint of generated SSH key.
+  returned: When I(generate_ssh_key) is C(True)
   type: str
   sample: '2048 SHA256:aYNHYcyVm87Igh0IMEDMbvW0QDlRQfE0aJugp684ko8 ansible-generated on host (RSA)'
 ssh_key_file:
-  description: Path to generated SSH private key file
-  returned: When C(generate_ssh_key) is C(True)
+  description: Path to generated SSH private key file.
+  returned: When I(generate_ssh_key) is C(True)
   type: str
   sample: /home/asmith/.ssh/id_rsa
 ssh_public_key:
-  description: Generated SSH public key file
-  returned: When C(generate_ssh_key) is C(True)
+  description: Generated SSH public key file.
+  returned: When I(generate_ssh_key) is C(True)
   type: str
   sample: >
     'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC95opt4SPEC06tOYsJQJIuN23BbLMGmYo8ysVZQc4h2DZE9ugbjWWGS1/pweUGjVstgzMkBEeBCByaEf/RJKNecKRPeGd2Bw9DCj/bn5Z6rGfNENKBmo
     618mUJBvdlEgea96QGjOwSB7/gmonduC7gsWDMNcOdSE3wJMTim4lddiBx4RgC9yXsJ6Tkz9BHD73MXPpT5ETnse+A3fw3IGVSjaueVnlUyUmOBf7fzmZbhlFVXf2Zi2rFTXqvbdGHKkzpw1U8eB8xFPP7y
     d5u1u0e6Acju/8aZ/l17IDFiLke5IzlqIMRTEbDwLNeO84YQKWTm9fODHzhYe0yvxqLiK07 ansible-generated on host'
 stderr:
-  description: Standard error from running commands
+  description: Standard error from running commands.
   returned: When stderr is returned by a command that is run
   type: str
   sample: Group wheels does not exist
 stdout:
-  description: Standard output from running commands
+  description: Standard output from running commands.
   returned: When standard output is returned by the command that is run
   type: str
   sample:
 system:
-  description: Whether or not the account is a system account
-  returned: When C(system) is passed to the module and the account does not exist
+  description: Whether or not the account is a system account.
+  returned: When I(system) is passed to the module and the account does not exist
   type: bool
   sample: True
 uid:
-  description: User ID of the user account
-  returned: When C(UID) is passed to the module
+  description: User ID of the user account.
+  returned: When I(uid) is passed to the module
   type: int
   sample: 1044
 '''