From 4544ec3b6a23f83827116927e738efcaacdb5ce0 Mon Sep 17 00:00:00 2001
From: Terry Howe <terrylhowe@gmail.com>
Date: Tue, 1 Jul 2014 17:32:59 -0600
Subject: [PATCH] Add some comments to the examples

Add some useful usage comments to the examples.

Change-Id: Id12ba3883492d69f971b78c75048fc7f5914998d
---
 examples/authenticate.py | 15 +++++++++++++++
 examples/common.py       | 12 +++++++++---
 examples/create.py       |  8 ++++++++
 examples/delete.py       |  8 ++++++++
 examples/get.py          |  8 ++++++++
 examples/session.py      | 10 ++++++++++
 examples/transport.py    |  8 ++++----
 7 files changed, 62 insertions(+), 7 deletions(-)

diff --git a/examples/authenticate.py b/examples/authenticate.py
index 9a02beffe..981c62c6b 100644
--- a/examples/authenticate.py
+++ b/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
diff --git a/examples/common.py b/examples/common.py
index cee2e1746..909fcf182 100755
--- a/examples/common.py
+++ b/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
diff --git a/examples/create.py b/examples/create.py
index 9745605e9..485726962 100644
--- a/examples/create.py
+++ b/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
diff --git a/examples/delete.py b/examples/delete.py
index 9113a6de6..413ff4914 100644
--- a/examples/delete.py
+++ b/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
diff --git a/examples/get.py b/examples/get.py
index bf9606b92..81aae8115 100644
--- a/examples/get.py
+++ b/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
diff --git a/examples/session.py b/examples/session.py
index 6683e2b79..93862de9a 100644
--- a/examples/session.py
+++ b/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
diff --git a/examples/transport.py b/examples/transport.py
index e3b0c207a..70c9b8be1 100755
--- a/examples/transport.py
+++ b/examples/transport.py
@@ -14,11 +14,11 @@
 # under the License.
 
 """
-SDK Transport Examples
-
-This script shows the basic use of the Transport class in making
-REST API calls.
+Transport Example
 
+For example:
+    python -m examples.transport \
+           https://region-a.geo-1.identity.hpcloudsvc.com:35357/
 """
 
 import sys