Add some comments to the examples

Add some useful usage comments to the examples.

Change-Id: Id12ba3883492d69f971b78c75048fc7f5914998d

examples/authenticate.py

@@ -10,6 +10,21 @@
 # License for the specific language governing permissions and limitations
 # under the License.
 
+"""
+Authentication example
+
+To authenticate you must have the environment variables set or use the
+command line options.  This is a good example to start wtih because once
+you know you can authenticate, you can perform other operations that
+require authentication.  Refer to the example common.py for the environment
+variables or command line options to use.
+
+If you use the environment variables, authenticate with:
+
+     python -m examples.authenticate
+
+"""
+
 import sys
 
 from examples import common

examples/common.py

@@ -14,16 +14,22 @@
 # under the License.
 
 """
-SDK Examples
+SDK Examples Common
 
 This is a collection of common functions used by the example scripts.
-It may also be run as a script to do the most basic check of creating
-a Transport object.
 
 common.object_parser() provides the common set of command-line arguments
 used in the library CLIs for setting up authentication.  This should make
 playing with the example scripts against a running OpenStack simpler.
 
+Typical environment variables to set and export for authentication include:
+
+    OS_PROJECT_NAME=FooFighter
+    OS_PASSWORD=nirvana
+    OS_AUTH_URL=https://foofighters.com:35357/v3
+    OS_USERNAME=davegrohl
+    OS_REGION=Seattle
+
 """
 
 import argparse

examples/create.py

@@ -10,6 +10,14 @@
 # License for the specific language governing permissions and limitations
 # under the License.
 
+"""
+Example Create Command
+
+For example:
+    python -m examples.create openstack/network/v2_0/network.py \
+           --data '{"name": "foo"}'
+"""
+
 import sys
 
 from examples import common

examples/delete.py

@@ -10,6 +10,14 @@
 # License for the specific language governing permissions and limitations
 # under the License.
 
+"""
+Example Delete Command
+
+For example:
+    python -m examples.delete openstack/network/v2_0/network.py \
+           --data '{"id": "a1369557-748f-429c-bd3e-fc385aacaec7"}'
+"""
+
 import sys
 
 from examples import common

examples/get.py

@@ -10,6 +10,14 @@
 # License for the specific language governing permissions and limitations
 # under the License.
 
+"""
+Example Get Command
+
+For example:
+    python -m examples.get openstack/network/v2_0/network.py \
+           --data '{"id": "a1369557-748f-429c-bd3e-fc385aacaec7"}'
+"""
+
 import sys
 
 from examples import common

examples/session.py

@@ -10,6 +10,16 @@
 # License for the specific language governing permissions and limitations
 # under the License.
 
+"""
+Example Session Command
+
+Make sure you can authenticate before running this command.  This command
+is currently hard coded to use the Identity service.
+
+For example:
+    python -m examples.session /tenants
+"""
+
 import sys
 
 from examples import authenticate

examples/transport.py

@@ -14,11 +14,11 @@
 # under the License.
 
 """
-SDK Transport Examples
+Transport Example
-
-This script shows the basic use of the Transport class in making
-REST API calls.
 
+For example:
+    python -m examples.transport \
+           https://region-a.geo-1.identity.hpcloudsvc.com:35357/
 """
 
 import sys