diff --git a/tools/build_bm.sh b/tools/build_bm.sh
index 44cf3030ee..b2d4c36668 100755
--- a/tools/build_bm.sh
+++ b/tools/build_bm.sh
@@ -1,4 +1,7 @@
 #!/usr/bin/env bash
+
+# **build_bm.sh**
+
 # Build an OpenStack install on a bare metal machine.
 set +x
 
diff --git a/tools/build_bm_multi.sh b/tools/build_bm_multi.sh
index 133d5372cf..f1242ee4f0 100755
--- a/tools/build_bm_multi.sh
+++ b/tools/build_bm_multi.sh
@@ -1,4 +1,7 @@
 #!/usr/bin/env bash
+
+# **build_bm_multi.sh**
+
 # Build an OpenStack install on several bare metal machines.
 SHELL_AFTER_RUN=no
 
diff --git a/tools/build_pxe_env.sh b/tools/build_pxe_env.sh
index d01dad0d07..e6f98b4b75 100755
--- a/tools/build_pxe_env.sh
+++ b/tools/build_pxe_env.sh
@@ -1,5 +1,8 @@
 #!/bin/bash -e
-# build_pxe_env.sh - Create a PXE boot environment
+
+# **build_pxe_env.sh**
+
+# Create a PXE boot environment
 #
 # build_pxe_env.sh destdir
 #
diff --git a/tools/build_ramdisk.sh b/tools/build_ramdisk.sh
index 7c1600b1ec..8e2c0be9f4 100755
--- a/tools/build_ramdisk.sh
+++ b/tools/build_ramdisk.sh
@@ -1,7 +1,10 @@
 #!/bin/bash
-# build_ramdisk.sh - Build RAM disk images
 
-# exit on error to stop unexpected errors
+# **build_ramdisk.sh**
+
+# Build RAM disk images
+
+# Exit on error to stop unexpected errors
 set -o errexit
 
 if [ ! "$#" -eq "1" ]; then
@@ -84,7 +87,7 @@ fi
 # Finds the next available NBD device
 # Exits script if error connecting or none free
 # map_nbd image
-# returns full nbd device path
+# Returns full nbd device path
 function map_nbd {
     for i in `seq 0 15`; do
         if [ ! -e /sys/block/nbd$i/pid ]; then
@@ -105,7 +108,7 @@ function map_nbd {
     echo $NBD
 }
 
-# prime image with as many apt/pips as we can
+# Prime image with as many apt/pips as we can
 DEV_FILE=$CACHEDIR/$DIST_NAME-dev.img
 DEV_FILE_TMP=`mktemp $DEV_FILE.XXXXXX`
 if [ ! -r $DEV_FILE ]; then
@@ -127,11 +130,11 @@ if [ ! -r $DEV_FILE ]; then
     mkdir -p $MNTDIR/$DEST
     chroot $MNTDIR chown stack $DEST
 
-    # a simple password - pass
+    # A simple password - pass
     echo stack:pass | chroot $MNTDIR chpasswd
     echo root:$ROOT_PASSWORD | chroot $MNTDIR chpasswd
 
-    # and has sudo ability (in the future this should be limited to only what
+    # And has sudo ability (in the future this should be limited to only what
     # stack requires)
     echo "stack ALL=(ALL) NOPASSWD: ALL" >> $MNTDIR/etc/sudoers
 
@@ -143,7 +146,8 @@ if [ ! -r $DEV_FILE ]; then
 fi
 rm -f $DEV_FILE_TMP
 
-# clone git repositories onto the system
+
+# Clone git repositories onto the system
 # ======================================
 
 IMG_FILE_TMP=`mktemp $IMG_FILE.XXXXXX`
diff --git a/tools/build_tempest.sh b/tools/build_tempest.sh
index 230e8f9b72..e72355c9c4 100755
--- a/tools/build_tempest.sh
+++ b/tools/build_tempest.sh
@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
 #
-# build_tempest.sh - Checkout and prepare a Tempest repo
-#                    (https://github.com/openstack/tempest.git)
+# **build_tempest.sh**
+
+# Checkout and prepare a Tempest repo: https://github.com/openstack/tempest.git
 
 function usage {
     echo "$0 - Check out and prepare a Tempest repo"
diff --git a/tools/build_uec.sh b/tools/build_uec.sh
index 35a4d6dbba..48819c95e7 100755
--- a/tools/build_uec.sh
+++ b/tools/build_uec.sh
@@ -1,5 +1,7 @@
 #!/usr/bin/env bash
 
+# **build_uec.sh**
+
 # Make sure that we have the proper version of ubuntu (only works on oneiric)
 if ! egrep -q "oneiric" /etc/lsb-release; then
     echo "This script only works with ubuntu oneiric."
diff --git a/tools/build_uec_ramdisk.sh b/tools/build_uec_ramdisk.sh
index 32f90c05c0..150ecabd64 100755
--- a/tools/build_uec_ramdisk.sh
+++ b/tools/build_uec_ramdisk.sh
@@ -1,7 +1,10 @@
 #!/usr/bin/env bash
-# build_uec_ramdisk.sh - Build RAM disk images based on UEC image
 
-# exit on error to stop unexpected errors
+# **build_uec_ramdisk.sh**
+
+# Build RAM disk images based on UEC image
+
+# Exit on error to stop unexpected errors
 set -o errexit
 
 if [ ! "$#" -eq "1" ]; then
@@ -58,7 +61,7 @@ DIST_NAME=${DIST_NAME:-oneiric}
 # Configure how large the VM should be
 GUEST_SIZE=${GUEST_SIZE:-2G}
 
-# exit on error to stop unexpected errors
+# Exit on error to stop unexpected errors
 set -o errexit
 set -o xtrace
 
diff --git a/tools/build_usb_boot.sh b/tools/build_usb_boot.sh
index cca2a681d6..f64b7b6866 100755
--- a/tools/build_usb_boot.sh
+++ b/tools/build_usb_boot.sh
@@ -1,5 +1,8 @@
 #!/bin/bash -e
-# build_usb_boot.sh - Create a syslinux boot environment
+
+# **build_usb_boot.sh**
+
+# Create a syslinux boot environment
 #
 # build_usb_boot.sh destdev
 #
diff --git a/tools/configure_tempest.sh b/tools/configure_tempest.sh
index 7a720455c8..bb995f8ca9 100755
--- a/tools/configure_tempest.sh
+++ b/tools/configure_tempest.sh
@@ -1,6 +1,8 @@
 #!/usr/bin/env bash
 #
-# configure_tempest.sh - Build a tempest configuration file from devstack
+# **configure_tempest.sh**
+
+# Build a tempest configuration file from devstack
 
 echo "**************************************************"
 echo "Configuring Tempest"
diff --git a/tools/copy_dev_environment_to_uec.sh b/tools/copy_dev_environment_to_uec.sh
index d5687dc14d..683a0d6a55 100755
--- a/tools/copy_dev_environment_to_uec.sh
+++ b/tools/copy_dev_environment_to_uec.sh
@@ -1,5 +1,7 @@
 #!/usr/bin/env bash
 
+# **copy_dev_environment_to_uec.sh**
+
 # Echo commands
 set -o xtrace
 
diff --git a/tools/get_uec_image.sh b/tools/get_uec_image.sh
index 09630740dc..ca74a030bd 100755
--- a/tools/get_uec_image.sh
+++ b/tools/get_uec_image.sh
@@ -1,5 +1,8 @@
 #!/bin/bash
-# get_uec_image.sh - Prepare Ubuntu UEC images
+
+# **get_uec_image.sh**
+
+# Download and prepare Ubuntu UEC images
 
 CACHEDIR=${CACHEDIR:-/opt/stack/cache}
 ROOTSIZE=${ROOTSIZE:-2000}
@@ -11,12 +14,12 @@ TOP_DIR=$(cd $TOOLS_DIR/..; pwd)
 # Import common functions
 . $TOP_DIR/functions
 
-# exit on error to stop unexpected errors
+# Exit on error to stop unexpected errors
 set -o errexit
 set -o xtrace
 
 usage() {
-    echo "Usage: $0 - Fetch and prepare Ubuntu images"
+    echo "Usage: $0 - Download and prepare Ubuntu UEC images"
     echo ""
     echo "$0 [-r rootsize] release imagefile [kernel]"
     echo ""
diff --git a/tools/info.sh b/tools/info.sh
index edff617f96..bdca06e8a3 100755
--- a/tools/info.sh
+++ b/tools/info.sh
@@ -1,5 +1,8 @@
 #!/usr/bin/env bash
-# info.sh - Produce a report on the state of devstack installs
+
+# **info.sh**
+
+# Produce a report on the state of devstack installs
 #
 # Output fields are separated with '|' chars
 # Output types are git,localrc,os,pip,pkg:
diff --git a/tools/install_openvpn.sh b/tools/install_openvpn.sh
index 44eee728e2..2f52aa14d0 100755
--- a/tools/install_openvpn.sh
+++ b/tools/install_openvpn.sh
@@ -1,5 +1,8 @@
 #!/bin/bash
-# install_openvpn.sh - Install OpenVPN and generate required certificates
+
+# **install_openvpn.sh**
+
+# Install OpenVPN and generate required certificates
 #
 # install_openvpn.sh --client name
 # install_openvpn.sh --server [name]
diff --git a/tools/warm_apts_and_pips_for_uec.sh b/tools/warm_apts_and_pips_for_uec.sh
index 23a28decec..fe389ffee6 100755
--- a/tools/warm_apts_and_pips_for_uec.sh
+++ b/tools/warm_apts_and_pips_for_uec.sh
@@ -1,5 +1,7 @@
 #!/usr/bin/env bash
 
+# **warm_apts_and_pips_for_uec.sh**
+
 # Echo commands
 set -o xtrace