Fix example format in Ansible modules (#69509)

* Fix example format in several Ansible modules
* Update lib/ansible/modules/fail.py
* Update lib/ansible/modules/pip.py

Co-authored-by: Felix Fontein <felix@fontein.de>

29 files changed, 191 insertions, 186 deletions

diff --git a/lib/ansible/modules/apt.py b/lib/ansible/modules/apt.py
index 1fc5a34d20..bee314e601 100644
--- a/lib/ansible/modules/apt.py
+++ b/lib/ansible/modules/apt.py
@@ -236,7 +236,7 @@ EXAMPLES = '''
     pkg: foo
     state: build-dep
 
-- name: Install a .deb package from the internet.
+- name: Install a .deb package from the internet
   apt:
     deb: https://example.com/python-ppq_0.1-1_all.deb
 
diff --git a/lib/ansible/modules/apt_repository.py b/lib/ansible/modules/apt_repository.py
index f94cf6ad35..db14521665 100644
--- a/lib/ansible/modules/apt_repository.py
+++ b/lib/ansible/modules/apt_repository.py
@@ -82,34 +82,33 @@ requirements:
 '''
 
 EXAMPLES = '''
-# Add specified repository into sources list.
-- apt_repository:
+- name: Add specified repository into sources list
+  apt_repository:
     repo: deb http://archive.canonical.com/ubuntu hardy partner
     state: present
 
-# Add specified repository into sources list using specified filename.
-- apt_repository:
+- name: Add specified repository into sources list using specified filename
+  apt_repository:
     repo: deb http://dl.google.com/linux/chrome/deb/ stable main
     state: present
     filename: google-chrome
 
-# Add source repository into sources list.
-- apt_repository:
+- name: Add source repository into sources list
+  apt_repository:
     repo: deb-src http://archive.canonical.com/ubuntu hardy partner
     state: present
 
-# Remove specified repository from sources list.
-- apt_repository:
+- name: Remove specified repository from sources list
+  apt_repository:
     repo: deb http://archive.canonical.com/ubuntu hardy partner
     state: absent
 
-# Add nginx stable repository from PPA and install its signing key.
-# On Ubuntu target:
-- apt_repository:
+- name: Add nginx stable repository from PPA and install its signing key on Ubuntu target
+  apt_repository:
     repo: ppa:nginx/stable
 
-# On Debian target
-- apt_repository:
+- name: Add nginx stable repository from PPA and install its signing key on Debian target
+  apt_repository:
     repo: 'ppa:nginx/stable'
     codename: trusty
 '''
diff --git a/lib/ansible/modules/assert.py b/lib/ansible/modules/assert.py
index cf66d5264c..9d251262d0 100644
--- a/lib/ansible/modules/assert.py
+++ b/lib/ansible/modules/assert.py
@@ -77,7 +77,7 @@ EXAMPLES = r'''
       - my_param >= 0
     msg: "'my_param' must be between 0 and 100"
 
-- name: use quiet to avoid verbose output
+- name: Use quiet to avoid verbose output
   assert:
     that:
       - my_param <= 100
diff --git a/lib/ansible/modules/command.py b/lib/ansible/modules/command.py
index 6aa4391e5e..2ebf7f743a 100644
--- a/lib/ansible/modules/command.py
+++ b/lib/ansible/modules/command.py
@@ -104,28 +104,28 @@ author:
 '''
 
 EXAMPLES = r'''
-- name: return motd to registered var
+- name: Return motd to registered var
   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').
+- 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
 
 # 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).
+- name: Run command if /path/to/database does not exist (with 'args' keyword)
   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).
+- name: Run command if /path/to/database does not exist (with 'cmd' parameter)
   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.
+- 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
   become: yes
   become_user: db_owner
@@ -143,7 +143,7 @@ EXAMPLES = r'''
       - dbname with whitespace
     creates: /path/to/database
 
-- name: safely use templated variable to run command. Always use the quote filter to avoid injection issues.
+- name: Safely use templated variable to run command. Always use the quote filter to avoid injection issues
   command: cat {{ myfile|quote }}
   register: myoutput
 '''
diff --git a/lib/ansible/modules/debconf.py b/lib/ansible/modules/debconf.py
index 3466e0a92c..eaeae1a39d 100644
--- a/lib/ansible/modules/debconf.py
+++ b/lib/ansible/modules/debconf.py
@@ -68,7 +68,7 @@ EXAMPLES = r'''
     value: fr_FR.UTF-8
     vtype: select
 
-- name: set to generate locales
+- name: Set to generate locales
   debconf:
     name: locales
     question: locales/locales_to_be_generated
diff --git a/lib/ansible/modules/dnf.py b/lib/ansible/modules/dnf.py
index a8625ed3d4..4d4f73f90b 100644
--- a/lib/ansible/modules/dnf.py
+++ b/lib/ansible/modules/dnf.py
@@ -221,45 +221,45 @@ author:
 '''
 
 EXAMPLES = '''
-- name: install the latest version of Apache
+- name: Install the latest version of Apache
   dnf:
     name: httpd
     state: latest
 
-- name: install the latest version of Apache and MariaDB
+- name: Install the latest version of Apache and MariaDB
   dnf:
     name:
       - httpd
       - mariadb-server
     state: latest
 
-- name: remove the Apache package
+- name: Remove the Apache package
   dnf:
     name: httpd
     state: absent
 
-- name: install the latest version of Apache from the testing repo
+- name: Install the latest version of Apache from the testing repo
   dnf:
     name: httpd
     enablerepo: testing
     state: present
 
-- name: upgrade all packages
+- name: Upgrade all packages
   dnf:
     name: "*"
     state: latest
 
-- name: install the nginx rpm from a remote repo
+- name: Install the nginx rpm from a remote repo
   dnf:
     name: 'http://nginx.org/packages/centos/6/noarch/RPMS/nginx-release-centos-6-0.el6.ngx.noarch.rpm'
     state: present
 
-- name: install nginx rpm from a local file
+- name: Install nginx rpm from a local file
   dnf:
     name: /usr/local/src/nginx-release-centos-6-0.el6.ngx.noarch.rpm
     state: present
 
-- name: install the 'Development tools' package group
+- name: Install the 'Development tools' package group
   dnf:
     name: '@Development tools'
     state: present
@@ -274,17 +274,17 @@ EXAMPLES = '''
     state: absent
     autoremove: no
 
-- name: install a modularity appstream with defined stream and profile
+- name: Install a modularity appstream with defined stream and profile
   dnf:
     name: '@postgresql:9.6/client'
     state: present
 
-- name: install a modularity appstream with defined stream
+- name: Install a modularity appstream with defined stream
   dnf:
     name: '@postgresql:9.6'
     state: present
 
-- name: install a modularity appstream with defined profile
+- name: Install a modularity appstream with defined profile
   dnf:
     name: '@postgresql/client'
     state: present
diff --git a/lib/ansible/modules/dpkg_selections.py b/lib/ansible/modules/dpkg_selections.py
index ccfb89226d..2e35878ba3 100644
--- a/lib/ansible/modules/dpkg_selections.py
+++ b/lib/ansible/modules/dpkg_selections.py
@@ -36,8 +36,8 @@ notes:
     - This module won't cause any packages to be installed/removed/purged, use the C(apt) module for that.
 '''
 EXAMPLES = '''
-# Prevent python from being upgraded.
-- dpkg_selections:
+- name: Prevent python from being upgraded
+  dpkg_selections:
     name: python
     selection: hold
 '''
diff --git a/lib/ansible/modules/fail.py b/lib/ansible/modules/fail.py
index 2a10bdadf7..149049df8f 100644
--- a/lib/ansible/modules/fail.py
+++ b/lib/ansible/modules/fail.py
@@ -38,8 +38,8 @@ author:
 '''
 
 EXAMPLES = r'''
-# Example playbook using fail and when together
-- fail:
+- name: Example using fail and when together
+  fail:
     msg: The system may not be provisioned according to the CMDB status.
   when: cmdb_status != "to-be-staged"
 '''
diff --git a/lib/ansible/modules/getent.py b/lib/ansible/modules/getent.py
index ae4a901a8b..29337b0cfb 100644
--- a/lib/ansible/modules/getent.py
+++ b/lib/ansible/modules/getent.py
@@ -51,36 +51,36 @@ author:
 '''
 
 EXAMPLES = '''
-# get root user info
-- getent:
+- name: Get root user info
+  getent:
     database: passwd
     key: root
 - debug:
     var: getent_passwd
 
-# get all groups
-- getent:
+- name: Get all groups
+  getent:
     database: group
     split: ':'
 - debug:
     var: getent_group
 
-# get all hosts, split by tab
-- getent:
+- name: Get all hosts, split by tab
+  getent:
     database: hosts
 - debug:
     var: getent_hosts
 
-# get http service info, no error if missing
-- getent:
+- name: Get http service info, no error if missing
+  getent:
     database: services
     key: http
     fail_key: False
 - debug:
     var: getent_services
 
-# get user password hash (requires sudo/root)
-- getent:
+- name: Get user password hash (requires sudo/root)
+  getent:
     database: shadow
     key: www-data
     split: ':'
diff --git a/lib/ansible/modules/git.py b/lib/ansible/modules/git.py
index bff6918432..4b4d740d7f 100644
--- a/lib/ansible/modules/git.py
+++ b/lib/ansible/modules/git.py
@@ -196,45 +196,44 @@ notes:
 '''
 
 EXAMPLES = '''
-# Example git checkout from Ansible Playbooks
-- git:
+- name: Git checkout
+  git:
     repo: 'https://foosball.example.org/path/to/repo.git'
     dest: /srv/checkout
     version: release-0.22
 
-# Example read-write git checkout from github
-- git:
+- name: Read-write git checkout from github
+  git:
     repo: git@github.com:mylogin/hello.git
     dest: /home/mylogin/hello
 
-# Example just ensuring the repo checkout exists
-- git:
+- name: Just ensuring the repo checkout exists
+  git:
     repo: 'https://foosball.example.org/path/to/repo.git'
     dest: /srv/checkout
     update: no
 
-# Example just get information about the repository whether or not it has
-# already been cloned locally.
-- git:
+- name: Just get information about the repository whether or not it has already been cloned locally
+  git:
     repo: 'https://foosball.example.org/path/to/repo.git'
     dest: /srv/checkout
     clone: no
     update: no
 
-# Example checkout a github repo and use refspec to fetch all pull requests
-- git:
+- name: Checkout a github repo and use refspec to fetch all pull requests
+  git:
     repo: https://github.com/ansible/ansible-examples.git
     dest: /src/ansible-examples
     refspec: '+refs/pull/*:refs/heads/*'
 
-# Example Create git archive from repo
-- git:
+- name: Create git archive from repo
+  git:
     repo: https://github.com/ansible/ansible-examples.git
     dest: /src/ansible-examples
     archive: /tmp/ansible-examples.zip
 
-# Example clone a repo with separate git directory
-- git:
+- name: Clone a repo with separate git directory
+  git:
     repo: https://github.com/ansible/ansible-examples.git
     dest: /src/ansible-examples
     separate_git_dir: /src/ansible-examples.git
diff --git a/lib/ansible/modules/group_by.py b/lib/ansible/modules/group_by.py
index 8572d606fd..5f43eea32d 100644
--- a/lib/ansible/modules/group_by.py
+++ b/lib/ansible/modules/group_by.py
@@ -41,16 +41,16 @@ author:
 '''
 
 EXAMPLES = r'''
-# Create groups based on the machine architecture
-- group_by:
+- name: Create groups based on the machine architecture
+  group_by:
     key: machine_{{ ansible_machine }}
 
-# Create groups like 'virt_kvm_host'
-- group_by:
+- name: Create groups like 'virt_kvm_host'
+  group_by:
     key: virt_{{ ansible_virtualization_type }}_{{ ansible_virtualization_role }}
 
-# Create nested groups
-- group_by:
+- name: Create nested groups
+  group_by:
     key: el{{ ansible_distribution_major_version }}-{{ ansible_architecture }}
     parents:
       - el{{ ansible_distribution_major_version }}
diff --git a/lib/ansible/modules/hostname.py b/lib/ansible/modules/hostname.py
index e9def3b038..07762b7f82 100644
--- a/lib/ansible/modules/hostname.py
+++ b/lib/ansible/modules/hostname.py
@@ -38,7 +38,8 @@ options:
 '''
 
 EXAMPLES = '''
-- hostname:
+- name: Set a hostname
+  hostname:
     name: web01
 '''
 
diff --git a/lib/ansible/modules/iptables.py b/lib/ansible/modules/iptables.py
index 8e4e6b134f..e6973689ed 100644
--- a/lib/ansible/modules/iptables.py
+++ b/lib/ansible/modules/iptables.py
@@ -371,7 +371,7 @@ EXAMPLES = r'''
     jump: ACCEPT
   become: yes
 
-- name: Allow new incoming SYN packets on TCP port 22 (SSH).
+- name: Allow new incoming SYN packets on TCP port 22 (SSH)
   iptables:
     chain: INPUT
     protocol: tcp
@@ -438,13 +438,13 @@ EXAMPLES = r'''
         - SYN
         - FIN
 
-- name: iptables flush filter
+- name: Iptables flush filter
   iptables:
     chain: "{{ item }}"
     flush: yes
   with_items:  [ 'INPUT', 'FORWARD', 'OUTPUT' ]
 
-- name: iptables flush nat
+- name: Iptables flush nat
   iptables:
     table: nat
     chain: '{{ item }}'
diff --git a/lib/ansible/modules/known_hosts.py b/lib/ansible/modules/known_hosts.py
index 5349f9f803..235019b018 100644
--- a/lib/ansible/modules/known_hosts.py
+++ b/lib/ansible/modules/known_hosts.py
@@ -59,7 +59,7 @@ author: "Matthew Vernon (@mcv21)"
 '''
 
 EXAMPLES = '''
-- name: tell the host about our servers it might want to ssh to
+- name: Tell the host about our servers it might want to ssh to
   known_hosts:
     path: /etc/ssh/ssh_known_hosts
     name: foo.com.invalid
diff --git a/lib/ansible/modules/package.py b/lib/ansible/modules/package.py
index b48a5dcf07..24ac099f20 100644
--- a/lib/ansible/modules/package.py
+++ b/lib/ansible/modules/package.py
@@ -49,18 +49,18 @@ notes:
     - For Windows targets, use the M(win_package) module instead.
 '''
 EXAMPLES = '''
-- name: install ntpdate
+- name: Install ntpdate
   package:
     name: ntpdate
     state: present
 
 # This uses a variable as this changes per distribution.
-- name: remove the apache package
+- name: Remove the apache package
   package:
     name: "{{ apache }}"
     state: absent
 
-- name: install the latest version of Apache and MariaDB
+- name: Install the latest version of Apache and MariaDB
   package:
     name:
       - httpd
diff --git a/lib/ansible/modules/pause.py b/lib/ansible/modules/pause.py
index 9fd8db5e0e..3b2b0e3799 100644
--- a/lib/ansible/modules/pause.py
+++ b/lib/ansible/modules/pause.py
@@ -50,19 +50,19 @@ notes:
 '''
 
 EXAMPLES = '''
-# Pause for 5 minutes to build app cache.
-- pause:
+- name: Pause for 5 minutes to build app cache
+  pause:
     minutes: 5
 
-# Pause until you can verify updates to an application were successful.
-- pause:
+- name: Pause until you can verify updates to an application were successful
+  pause:
 
-# A helpful reminder of what to look out for post-update.
-- pause:
+- name: A helpful reminder of what to look out for post-update
+  pause:
     prompt: "Make sure org.foo.FooOverload exception is not present"
 
-# Pause to get some sensitive input.
-- pause:
+- name: Pause to get some sensitive input
+  pause:
     prompt: "Enter a secret"
     echo: no
 '''
diff --git a/lib/ansible/modules/ping.py b/lib/ansible/modules/ping.py
index 4cf384b35f..460f2a7aee 100644
--- a/lib/ansible/modules/ping.py
+++ b/lib/ansible/modules/ping.py
@@ -44,11 +44,11 @@ EXAMPLES = '''
 # Test we can logon to 'webservers' and execute python with json lib.
 # ansible webservers -m ping
 
-# Example from an Ansible Playbook
-- ping:
+- name: Example from an Ansible Playbook
+  ping:
 
-# Induce an exception to see what happens
-- ping:
+- name: Induce an exception to see what happens
+  ping:
     data: crash
 '''
 
diff --git a/lib/ansible/modules/pip.py b/lib/ansible/modules/pip.py
index 9ce74e6b09..80b02ef010 100644
--- a/lib/ansible/modules/pip.py
+++ b/lib/ansible/modules/pip.py
@@ -134,96 +134,98 @@ author:
 '''
 
 EXAMPLES = '''
-# Install (Bottle) python package.
-- pip:
+- name: Install bottle python package
+  pip:
     name: bottle
 
-# Install (Bottle) python package on version 0.11.
-- pip:
+- name: Install bottle python package on version 0.11
+  pip:
     name: bottle==0.11
 
-# Install (bottle) python package with version specifiers
-- pip:
+- name: Install bottle python package with version specifiers
+  pip:
     name: bottle>0.10,<0.20,!=0.11
 
-# Install multi python packages with version specifiers
-- pip:
+- name: Install multi python packages with version specifiers
+  pip:
     name:
       - django>1.11.0,<1.12.0
       - bottle>0.10,<0.20,!=0.11
 
-# Install python package using a proxy - it doesn't use the standard environment variables, please use the CAPITALIZED ones below
-- pip:
+- name: Install python package using a proxy
+  # Pip doesn't use the standard environment variables, please use the CAPITALIZED ones below
+  pip:
     name: six
   environment:
     HTTP_PROXY: '127.0.0.1:8080'
     HTTPS_PROXY: '127.0.0.1:8080'
 
-# Install (MyApp) using one of the remote protocols (bzr+,hg+,git+,svn+). You do not have to supply '-e' option in extra_args.
-- pip:
+# You do not have to supply '-e' option in extra_args
+- name: Install MyApp using one of the remote protocols (bzr+,hg+,git+,svn+)
+  pip:
     name: svn+http://myrepo/svn/MyApp#egg=MyApp
 
-# Install MyApp using one of the remote protocols (bzr+,hg+,git+).
-- pip:
+- name: Install MyApp using one of the remote protocols (bzr+,hg+,git+)
+  pip:
     name: git+http://myrepo/app/MyApp
 
-# Install (MyApp) from local tarball
-- pip:
+- name: Install MyApp from local tarball
+  pip:
     name: file:///path/to/MyApp.tar.gz
 
-# Install (Bottle) into the specified (virtualenv), inheriting none of the globally installed modules
-- pip:
+- name: Install bottle into the specified (virtualenv), inheriting none of the globally installed modules
+  pip:
     name: bottle
     virtualenv: /my_app/venv
 
-# Install (Bottle) into the specified (virtualenv), inheriting globally installed modules
-- pip:
+- name: Install bottle into the specified (virtualenv), inheriting globally installed modules
+  pip:
     name: bottle
     virtualenv: /my_app/venv
     virtualenv_site_packages: yes
 
-# Install (Bottle) into the specified (virtualenv), using Python 2.7
-- pip:
+- name: Install bottle into the specified (virtualenv), using Python 2.7
+  pip:
     name: bottle
     virtualenv: /my_app/venv
     virtualenv_command: virtualenv-2.7
 
-# Install (Bottle) within a user home directory.
-- pip:
+- name: Install bottle within a user home directory
+  pip:
     name: bottle
     extra_args: --user
 
-# Install specified python requirements.
-- pip:
+- name: Install specified python requirements
+  pip:
     requirements: /my_app/requirements.txt
 
-# Install specified python requirements in indicated (virtualenv).
-- pip:
+- name: Install specified python requirements in indicated (virtualenv)
+  pip:
     requirements: /my_app/requirements.txt
     virtualenv: /my_app/venv
 
-# Install specified python requirements and custom Index URL.
-- pip:
+- name: Install specified python requirements and custom Index URL
+  pip:
     requirements: /my_app/requirements.txt
     extra_args: -i https://example.com/pypi/simple
 
-# Install specified python requirements offline from a local directory with downloaded packages.
-- pip:
+- name: Install specified python requirements offline from a local directory with downloaded packages
+  pip:
     requirements: /my_app/requirements.txt
     extra_args: "--no-index --find-links=file:///my_downloaded_packages_dir"
 
-# Install (Bottle) for Python 3.3 specifically,using the 'pip3.3' executable.
-- pip:
+- name: Install bottle for Python 3.3 specifically, using the 'pip3.3' executable
+  pip:
     name: bottle
     executable: pip3.3
 
-# Install (Bottle), forcing reinstallation if it's already installed
-- pip:
+- name: Install bottle, forcing reinstallation if it's already installed
+  pip:
     name: bottle
     state: forcereinstall
 
-# Install (Bottle) while ensuring the umask is 0022 (to ensure other users can use it)
-- pip:
+- name: Install bottle while ensuring the umask is 0022 (to ensure other users can use it)
+  pip:
     name: bottle
     umask: "0022"
   become: True
diff --git a/lib/ansible/modules/rpm_key.py b/lib/ansible/modules/rpm_key.py
index f64992e944..74a9d50079 100644
--- a/lib/ansible/modules/rpm_key.py
+++ b/lib/ansible/modules/rpm_key.py
@@ -48,23 +48,23 @@ options:
 '''
 
 EXAMPLES = '''
-# Example action to import a key from a url
-- rpm_key:
+- name: Import a key from a url
+  rpm_key:
     state: present
     key: http://apt.sw.be/RPM-GPG-KEY.dag.txt
 
-# Example action to import a key from a file
-- rpm_key:
+- name: Import a key from a file
+  rpm_key:
     state: present
     key: /path/to/key.gpg
 
-# Example action to ensure a key is not present in the db
-- rpm_key:
+- name: Ensure a key is not present in the db
+  rpm_key:
     state: absent
     key: DEADB33F
 
-# Verify the key, using a fingerprint, before import
-- rpm_key:
+- name: Verify the key, using a fingerprint, before import
+  rpm_key:
     key: /path/to/RPM-GPG-KEY.dag.txt
     fingerprint: EBC6 E12C 62B1 C734 026B  2122 A20E 5214 6B8D 79E6
 '''
diff --git a/lib/ansible/modules/service_facts.py b/lib/ansible/modules/service_facts.py
index 5f8b4d52d9..b3a4e74664 100644
--- a/lib/ansible/modules/service_facts.py
+++ b/lib/ansible/modules/service_facts.py
@@ -35,7 +35,7 @@ author:
 '''
 
 EXAMPLES = '''
-- name: populate service facts
+- name: Populate service facts
   service_facts:
 
 - debug:
diff --git a/lib/ansible/modules/set_fact.py b/lib/ansible/modules/set_fact.py
index 5ee512cbd9..e3394fbe04 100644
--- a/lib/ansible/modules/set_fact.py
+++ b/lib/ansible/modules/set_fact.py
@@ -57,17 +57,17 @@ author:
 '''
 
 EXAMPLES = r'''
-# Example setting host facts using key=value pairs, note that this always creates strings or booleans
-- set_fact: one_fact="something" other_fact="{{ local_var }}"
+- name: Setting host facts using key=value pairs, note that this always creates strings or booleans
+  set_fact: one_fact="something" other_fact="{{ local_var }}"
 
-# Example setting host facts using complex arguments
-- set_fact:
+- name: Setting host facts using complex arguments
+  set_fact:
     one_fact: something
     other_fact: "{{ local_var * 2 }}"
     another_fact: "{{ some_registered_var.results | map(attribute='ansible_facts.some_fact') | list }}"
 
-# Example setting facts so that they will be persisted in the fact cache
-- set_fact:
+- name: Setting facts so that they will be persisted in the fact cache
+  set_fact:
     one_fact: something
     other_fact: "{{ local_var * 2 }}"
     cacheable: yes
@@ -75,7 +75,8 @@ EXAMPLES = r'''
 # As of Ansible 1.8, Ansible will convert boolean strings ('true', 'false', 'yes', 'no')
 # to proper boolean values when using the key=value syntax, however it is still
 # recommended that booleans be set using the complex argument style:
-- set_fact:
+- name:  Setting booleans using complex argument style
+  set_fact:
     one_fact: yes
     other_fact: no
 
diff --git a/lib/ansible/modules/set_stats.py b/lib/ansible/modules/set_stats.py
index d35160b38b..95109e96a6 100644
--- a/lib/ansible/modules/set_stats.py
+++ b/lib/ansible/modules/set_stats.py
@@ -42,14 +42,14 @@ version_added: "2.3"
 '''
 
 EXAMPLES = r'''
-# Aggregating packages_installed stat per host
-- set_stats:
+- name: Aggregating packages_installed stat per host
+  set_stats:
     data:
       packages_installed: 31
     per_host: yes
 
-# Aggregating random stats for all hosts using complex arguments
-- set_stats:
+- name: Aggregating random stats for all hosts using complex arguments
+  set_stats:
     data:
       one_stat: 11
       other_stat: "{{ local_var * 2 }}"
@@ -57,8 +57,8 @@ EXAMPLES = r'''
     per_host: no
 
 
-# setting stats (not aggregating)
-- set_stats:
+- name: Setting stats (not aggregating)
+  set_stats:
     data:
       the_answer: 42
     aggregate: no
diff --git a/lib/ansible/modules/shell.py b/lib/ansible/modules/shell.py
index 4dc4411a67..8066d7ad52 100644
--- a/lib/ansible/modules/shell.py
+++ b/lib/ansible/modules/shell.py
@@ -103,23 +103,23 @@ author:
 '''
 
 EXAMPLES = r'''
-- name: Execute the command in remote shell; stdout goes to the specified file on the remote.
+- name: Execute the command in remote shell; stdout goes to the specified file on the remote
   shell: somescript.sh >> somelog.txt
 
-- name: Change the working directory to somedir/ before executing the command.
+- name: Change the working directory to somedir/ before executing the command
   shell: somescript.sh >> somelog.txt
   args:
     chdir: somedir/
 
 # You can also use the 'args' form to provide the options.
-- name: This command will change the working directory to somedir/ and will only run when somedir/somelog.txt doesn't exist.
+- name: This command will change the working directory to somedir/ and will only run when somedir/somelog.txt doesn't exist
   shell: somescript.sh >> somelog.txt
   args:
     chdir: somedir/
     creates: somelog.txt
 
 # You can also use the 'cmd' parameter instead of free form format.
-- name: This command will change the working directory to somedir/.
+- name: This command will change the working directory to somedir/
   shell:
     cmd: ls -l | grep log
     chdir: somedir/
@@ -153,7 +153,7 @@ EXAMPLES = r'''
   delegate_to: localhost
 
 # Disabling warnings
-- name: Using curl to connect to a host via SOCKS proxy (unsupported in uri). Ordinarily this would throw a warning.
+- name: Using curl to connect to a host via SOCKS proxy (unsupported in uri). Ordinarily this would throw a warning
   shell: curl --socks5 localhost:9000 http://www.ansible.com
   args:
     warn: no
diff --git a/lib/ansible/modules/stat.py b/lib/ansible/modules/stat.py
index 31bd132699..663d2c54a5 100644
--- a/lib/ansible/modules/stat.py
+++ b/lib/ansible/modules/stat.py
@@ -73,7 +73,8 @@ author: Bruce Pennypacker (@bpennypacker)
 EXAMPLES = r'''
 # Obtain the stats of /etc/foo.conf, and check that the file still belongs
 # to 'root'. Fail otherwise.
-- stat:
+- name: Get stats of a file
+  stat:
     path: /etc/foo.conf
   register: st
 - fail:
@@ -85,7 +86,8 @@ EXAMPLES = r'''
 # therefore, we must test whether it is defined.
 # Run this to understand the structure, the skipped ones do not pass the
 # check performed by 'when'
-- stat:
+- name: Get stats of the FS object
+  stat:
     path: /path/to/something
   register: sym
 
@@ -108,20 +110,21 @@ EXAMPLES = r'''
 
 # Determine if a path exists and is a directory.  Note that we need to test
 # both that p.stat.isdir actually exists, and also that it's set to true.
-- stat:
+- name: Get stats of the FS object
+  stat:
     path: /path/to/something
   register: p
 - debug:
     msg: "Path exists and is a directory"
   when: p.stat.isdir is defined and p.stat.isdir
 
-# Don't do checksum
-- stat:
+- name: Don't do checksum
+  stat:
     path: /path/to/myhugefile
     get_checksum: no
 
-# Use sha256 to calculate checksum
-- stat:
+- name: Use sha256 to calculate checksum
+  stat:
     path: /path/to/something
     checksum_algorithm: sha256
 '''
diff --git a/lib/ansible/modules/systemd.py b/lib/ansible/modules/systemd.py
index 8329a46ca8..25ac688cb3 100644
--- a/lib/ansible/modules/systemd.py
+++ b/lib/ansible/modules/systemd.py
@@ -96,39 +96,39 @@ EXAMPLES = '''
     state: started
     name: httpd
 
-- name: stop service cron on debian, if running
+- name: Stop service cron on debian, if running
   systemd:
     name: cron
     state: stopped
 
-- name: restart service cron on centos, in all cases, also issue daemon-reload to pick up config changes
+- name: Restart service cron on centos, in all cases, also issue daemon-reload to pick up config changes
   systemd:
     state: restarted
     daemon_reload: yes
     name: crond
 
-- name: reload service httpd, in all cases
+- name: Reload service httpd, in all cases
   systemd:
     name: httpd
     state: reloaded
 
-- name: enable service httpd and ensure it is not masked
+- name: Enable service httpd and ensure it is not masked
   systemd:
     name: httpd
     enabled: yes
     masked: no
 
-- name: enable a timer for dnf-automatic
+- name: Enable a timer for dnf-automatic
   systemd:
     name: dnf-automatic.timer
     state: started
     enabled: yes
 
-- name: just force systemd to reread configs (2.4 and above)
+- name: Just force systemd to reread configs (2.4 and above)
   systemd:
     daemon_reload: yes
 
-- name: just force systemd to re-execute itself (2.8 and above)
+- name: Just force systemd to re-execute itself (2.8 and above)
   systemd:
     daemon_reexec: yes
 '''
diff --git a/lib/ansible/modules/sysvinit.py b/lib/ansible/modules/sysvinit.py
index ecd0e8c2f8..779024865a 100644
--- a/lib/ansible/modules/sysvinit.py
+++ b/lib/ansible/modules/sysvinit.py
@@ -71,13 +71,13 @@ requirements:
 '''
 
 EXAMPLES = '''
-- name: make sure apache2 is started
+- name: Make sure apache2 is started
   sysvinit:
       name: apache2
       state: started
       enabled: yes
 
-- name: make sure apache2 is started on runlevels 3 and 5
+- name: Make sure apache2 is started on runlevels 3 and 5
   sysvinit:
       name: apache2
       state: started
diff --git a/lib/ansible/modules/tempfile.py b/lib/ansible/modules/tempfile.py
index 17d459aa29..08a56fbf7b 100644
--- a/lib/ansible/modules/tempfile.py
+++ b/lib/ansible/modules/tempfile.py
@@ -52,18 +52,18 @@ author:
 '''
 
 EXAMPLES = """
-- name: create temporary build directory
+- name: Create temporary build directory
   tempfile:
     state: directory
     suffix: build
 
-- name: create temporary file
+- name: Create temporary file
   tempfile:
     state: file
     suffix: temp
   register: tempfile_1
 
-- name: use the registered var and the file module to remove the temporary file
+- name: Use the registered var and the file module to remove the temporary file
   file:
     path: "{{ tempfile_1.path }}"
     state: absent
diff --git a/lib/ansible/modules/wait_for.py b/lib/ansible/modules/wait_for.py
index fdfbea545f..e11dfcb166 100644
--- a/lib/ansible/modules/wait_for.py
+++ b/lib/ansible/modules/wait_for.py
@@ -118,7 +118,7 @@ author:
 '''
 
 EXAMPLES = r'''
-- name: sleep for 300 seconds and continue with play
+- name: Sleep for 300 seconds and continue with play
   wait_for:
     timeout: 300
   delegate_to: localhost
diff --git a/lib/ansible/modules/yum.py b/lib/ansible/modules/yum.py
index 8d4cc4a522..ed6a3e9cec 100644
--- a/lib/ansible/modules/yum.py
+++ b/lib/ansible/modules/yum.py
@@ -241,12 +241,12 @@ author:
 '''
 
 EXAMPLES = '''
-- name: install the latest version of Apache
+- name: Install the latest version of Apache
   yum:
     name: httpd
     state: latest
 
-- name: install a list of packages (suitable replacement for 2.11 loop deprecation warning)
+- name: Install a list of packages (suitable replacement for 2.11 loop deprecation warning)
   yum:
     name:
       - nginx
@@ -254,7 +254,7 @@ EXAMPLES = '''
       - postgresql-server
     state: present
 
-- name: install a list of packages with a list variable
+- name: Install a list of packages with a list variable
   yum:
     name: "{{ packages }}"
   vars:
@@ -262,54 +262,54 @@ EXAMPLES = '''
     - httpd
     - httpd-tools
 
-- name: remove the Apache package
+- name: Remove the Apache package
   yum:
     name: httpd
     state: absent
 
-- name: install the latest version of Apache from the testing repo
+- name: Install the latest version of Apache from the testing repo
   yum:
     name: httpd
     enablerepo: testing
     state: present
 
-- name: install one specific version of Apache
+- name: Install one specific version of Apache
   yum:
     name: httpd-2.2.29-1.4.amzn1
     state: present
 
-- name: upgrade all packages
+- name: Upgrade all packages
   yum:
     name: '*'
     state: latest
 
-- name: upgrade all packages, excluding kernel & foo related packages
+- name: Upgrade all packages, excluding kernel & foo related packages
   yum:
     name: '*'
     state: latest
     exclude: kernel*,foo*
 
-- name: install the nginx rpm from a remote repo
+- name: Install the nginx rpm from a remote repo
   yum:
     name: http://nginx.org/packages/centos/6/noarch/RPMS/nginx-release-centos-6-0.el6.ngx.noarch.rpm
     state: present
 
-- name: install nginx rpm from a local file
+- name: Install nginx rpm from a local file
   yum:
     name: /usr/local/src/nginx-release-centos-6-0.el6.ngx.noarch.rpm
     state: present
 
-- name: install the 'Development tools' package group
+- name: Install the 'Development tools' package group
   yum:
     name: "@Development tools"
     state: present
 
-- name: install the 'Gnome desktop' environment group
+- name: Install the 'Gnome desktop' environment group
   yum:
     name: "@^gnome-desktop-environment"
     state: present
 
-- name: List ansible packages and register result to print with debug later.
+- name: List ansible packages and register result to print with debug later
   yum:
     list: ansible
   register: result