diff --git a/lib/tempest b/lib/tempest
index 8672a14..d86ee27 100644
--- a/lib/tempest
+++ b/lib/tempest
@@ -62,13 +62,11 @@
 # The default is set to 196 seconds.
 BUILD_TIMEOUT=${BUILD_TIMEOUT:-196}
 
-
 # This must be False on stable branches, as master tempest
 # deps do not match stable branch deps. Set this to True to
-# have tempest installed in devstack by default.
+# have tempest installed in DevStack by default.
 INSTALL_TEMPEST=${INSTALL_TEMPEST:-"True"}
 
-
 BOTO_MATERIALS_PATH="$FILES/images/s3-materials/cirros-${CIRROS_VERSION}"
 BOTO_CONF=/etc/boto.cfg
 
@@ -83,6 +81,7 @@
 IPV6_ENABLED=$(trueorfalse True IPV6_ENABLED)
 IPV6_SUBNET_ATTRIBUTES_ENABLED=$(trueorfalse True IPV6_SUBNET_ATTRIBUTES_ENABLED)
 
+
 # Functions
 # ---------
 
@@ -168,8 +167,8 @@
         esac
     fi
 
-    # Create tempest.conf from tempest.conf.sample
-    # copy every time, because the image UUIDS are going to change
+    # Create ``tempest.conf`` from ``tempest.conf.sample``
+    # Copy every time because the image UUIDS are going to change
     sudo install -d -o $STACK_USER $TEMPEST_CONFIG_DIR
     install -m 644 $TEMPEST_DIR/etc/tempest.conf.sample $TEMPEST_CONFIG
 
@@ -179,8 +178,8 @@
     # the cloud. We don't always want to so that we can ensure Tempest
     # would work on a public cloud.
     TEMPEST_HAS_ADMIN=$(trueorfalse True TEMPEST_HAS_ADMIN)
-    # See files/keystone_data.sh and stack.sh where admin, demo and alt_demo
-    # user and tenant are set up...
+
+    # See ``lib/keystone`` where these users and tenants are set up
     ADMIN_USERNAME=${ADMIN_USERNAME:-admin}
     ADMIN_TENANT_NAME=${ADMIN_TENANT_NAME:-admin}
     ADMIN_DOMAIN_NAME=${ADMIN_DOMAIN_NAME:-Default}
@@ -191,13 +190,13 @@
     ADMIN_TENANT_ID=$(openstack project list | awk "/ admin / { print \$2 }")
 
     if is_service_enabled nova; then
-        # If the ``DEFAULT_INSTANCE_TYPE`` not declared, use the new behavior
-        # Tempest creates instane types for himself
+        # If ``DEFAULT_INSTANCE_TYPE`` is not declared, use the new behavior
+        # Tempest creates its own instance types
         if  [[ -z "$DEFAULT_INSTANCE_TYPE" ]]; then
             available_flavors=$(nova flavor-list)
             if [[ ! ( $available_flavors =~ 'm1.nano' ) ]]; then
                 if is_arch "ppc64"; then
-                    # qemu needs at least 128MB of memory to boot on ppc64
+                    # Qemu needs at least 128MB of memory to boot on ppc64
                     nova flavor-create m1.nano 42 128 0 1
                 else
                     nova flavor-create m1.nano 42 64 0 1
@@ -214,8 +213,7 @@
             fi
             flavor_ref_alt=84
         else
-            # Check Nova for existing flavors and, if set, look for the
-            # ``DEFAULT_INSTANCE_TYPE`` and use that.
+            # Check Nova for existing flavors, if ``DEFAULT_INSTANCE_TYPE`` is set use it.
             boto_instance_type=$DEFAULT_INSTANCE_TYPE
             flavor_lines=`nova flavor-list`
             IFS=$'\r\n'
@@ -240,8 +238,8 @@
             flavor_ref=${flavors[0]}
             flavor_ref_alt=$flavor_ref
 
-            # ensure flavor_ref and flavor_ref_alt have different values
-            # some resize instance in tempest tests depends on this.
+            # Ensure ``flavor_ref`` and ``flavor_ref_alt`` have different values.
+            # Some resize instance in tempest tests depends on this.
             for f in ${flavors[@]:1}; do
                 if [[ $f -ne $flavor_ref ]]; then
                     flavor_ref_alt=$f
@@ -266,7 +264,7 @@
         public_network_id=$(neutron net-list | grep $PUBLIC_NETWORK_NAME | \
             awk '{print $2}')
         if [ "$Q_USE_NAMESPACE" == "False" ]; then
-            # If namespaces are disabled, devstack will create a single
+            # If namespaces are disabled, DevStack will create a single
             # public router that tempest should be configured to use.
             public_router_id=$(neutron router-list | awk "/ $Q_ROUTER_NAME / \
                 { print \$2 }")
@@ -274,6 +272,7 @@
     fi
 
     iniset $TEMPEST_CONFIG DEFAULT use_syslog $SYSLOG
+
     # Oslo
     iniset $TEMPEST_CONFIG oslo_concurrency lock_path $TEMPEST_STATE_PATH
     mkdir -p $TEMPEST_STATE_PATH
@@ -309,15 +308,13 @@
     fi
 
     # Image
-    # for the gate we want to be able to override this variable so we aren't
-    # doing an HTTP fetch over the wide internet for this test
+    # We want to be able to override this variable in the gate to avoid
+    # doing an external HTTP fetch for this test.
     if [[ ! -z "$TEMPEST_HTTP_IMAGE" ]]; then
         iniset $TEMPEST_CONFIG image http_image $TEMPEST_HTTP_IMAGE
     fi
 
     # Auth
-    #
-    #
     TEMPEST_ALLOW_TENANT_ISOLATION=${TEMPEST_ALLOW_TENANT_ISOLATION:-$TEMPEST_HAS_ADMIN}
     iniset $TEMPEST_CONFIG auth allow_tenant_isolation ${TEMPEST_ALLOW_TENANT_ISOLATION:-True}
     iniset $TEMPEST_CONFIG auth tempest_roles "Member"
@@ -336,7 +333,7 @@
     iniset $TEMPEST_CONFIG compute ssh_connect_method $ssh_connect_method
 
     # Compute Features
-    # Run verify_tempest_config -ur to retrieve enabled extensions on API endpoints
+    # Run ``verify_tempest_config -ur`` to retrieve enabled extensions on API endpoints
     # NOTE(mtreinish): This must be done after auth settings are added to the tempest config
     local tmp_cfg_file=$(mktemp)
     cd $TEMPEST_DIR
@@ -417,11 +414,11 @@
     iniset $TEMPEST_CONFIG scenario large_ops_number ${TEMPEST_LARGE_OPS_NUMBER:-0}
 
     # Telemetry
-    # Ceilometer API optimization happened in juno that allows to run more tests in tempest.
+    # Ceilometer API optimization happened in Juno that allows to run more tests in tempest.
     # Once Tempest retires support for icehouse this flag can be removed.
     iniset $TEMPEST_CONFIG telemetry too_slow_to_test "False"
 
-    # Object storage
+    # Object Store
     local object_storage_api_extensions=${OBJECT_STORAGE_API_EXTENSIONS:-"all"}
     if [[ ! -z "$DISABLE_OBJECT_STORAGE_API_EXTENSIONS" ]]; then
         # Enabled extensions are either the ones explicitly specified or those available on the API endpoint
@@ -445,7 +442,7 @@
         iniset $TEMPEST_CONFIG volume-feature-enabled backup False
     fi
 
-    # Using CINDER_ENABLED_BACKENDS
+    # Using ``CINDER_ENABLED_BACKENDS``
     if [[ -n "$CINDER_ENABLED_BACKENDS" ]] && [[ $CINDER_ENABLED_BACKENDS =~ .*,.* ]]; then
         iniset $TEMPEST_CONFIG volume-feature-enabled multi_backend "True"
         local i=1
@@ -470,7 +467,7 @@
     iniset $TEMPEST_CONFIG dashboard dashboard_url "http://$SERVICE_HOST/"
     iniset $TEMPEST_CONFIG dashboard login_url "http://$SERVICE_HOST/auth/login/"
 
-    # cli
+    # CLI
     iniset $TEMPEST_CONFIG cli cli_dir $NOVA_BIN_DIR
 
     # Baremetal
@@ -495,7 +492,7 @@
         iniset $TEMPEST_CONFIG compute-feature-enabled suspend False
     fi
 
-    # service_available
+    # ``service_available``
     for service in ${TEMPEST_SERVICES//,/ }; do
         if is_service_enabled $service ; then
             iniset $TEMPEST_CONFIG service_available $service "True"
@@ -505,7 +502,7 @@
     done
 
     if is_ssl_enabled_service "key" || is_service_enabled tls-proxy; then
-        # Use the BOTO_CONFIG environment variable to point to this file
+        # Use the ``BOTO_CONFIG`` environment variable to point to this file
         iniset $BOTO_CONF Boto ca_certificates_file $SSL_BUNDLE_FILE
         sudo chown $STACK_USER $BOTO_CONF
     fi
@@ -520,7 +517,6 @@
 # ------------------------------------------------------------------
 # alt_demo             alt_demo     Member
 
-# Migrated from keystone_data.sh
 function create_tempest_accounts {
     if is_service_enabled tempest; then
         # Tempest has some tests that validate various authorization checks
@@ -531,13 +527,13 @@
     fi
 }
 
-# install_tempest_lib() - Collect source, prepare, and install tempest-lib
+# install_tempest_lib() - Collect source, prepare, and install ``tempest-lib``
 function install_tempest_lib {
     if use_library_from_git "tempest-lib"; then
         git_clone_by_name "tempest-lib"
         setup_dev_lib "tempest-lib"
-        # NOTE(mtreinish) For testing tempest-lib from git with tempest we need
-        # put the git version of tempest-lib in the tempest job's tox venv
+        # NOTE(mtreinish) For testing ``tempest-lib`` from git with Tempest we need to
+        # put the git version of ``tempest-lib`` in the Tempest job's tox venv
         export PIP_VIRTUAL_ENV=${PROJECT_VENV["tempest"]}
         setup_dev_lib "tempest-lib"
         unset PIP_VIRTUAL_ENV
@@ -555,7 +551,7 @@
     popd
 }
 
-# init_tempest() - Initialize ec2 images
+# init_tempest() - Initialize EC2 images
 function init_tempest {
     local base_image_name=cirros-${CIRROS_VERSION}-${CIRROS_ARCH}
     # /opt/stack/devstack/files/images/cirros-${CIRROS_VERSION}-${CIRROS_ARCH}-uec
@@ -564,7 +560,7 @@
     local ramdisk="$image_dir/${base_image_name}-initrd"
     local disk_image="$image_dir/${base_image_name}-blank.img"
     if is_service_enabled nova; then
-        # if the cirros uec downloaded and the system is uec capable
+        # If the CirrOS uec downloaded and the system is UEC capable
         if [ -f "$kernel" -a -f "$ramdisk" -a -f "$disk_image" -a  "$VIRT_DRIVER" != "openvz" \
             -a \( "$LIBVIRT_TYPE" != "lxc" -o "$VIRT_DRIVER" != "libvirt" \) ]; then
             echo "Prepare aki/ari/ami Images"