From e352b607ee671feeb7c2ddb82462b3da7d3ce28a Mon Sep 17 00:00:00 2001
From: Felipe Monteiro <felipe.monteiro@att.com>
Date: Tue, 11 Jul 2017 16:03:36 +0100
Subject: [PATCH] Add additional documentation.

---
 deckhand/control/base.py                         |  3 +--
 deckhand/engine/secret_substitution.py           |  5 +++++
 .../unit/engine/test_secret_substitution.py      | 16 +++++++++++++++-
 3 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/deckhand/control/base.py b/deckhand/control/base.py
index 7b70498d..d6ba5146 100644
--- a/deckhand/control/base.py
+++ b/deckhand/control/base.py
@@ -63,8 +63,7 @@ class BaseResource(object):
                 return None
 
             try:
-                json_body = json.loads(raw_body.decode('utf-8'))
-                return json_body
+                return json.loads(raw_body.decode('utf-8'))
             except json.JSONDecodeError as jex:
                 raise errors.InvalidFormat("%s: Invalid JSON in body: %s" % (
                     req.path, jex))
diff --git a/deckhand/engine/secret_substitution.py b/deckhand/engine/secret_substitution.py
index 8a16c99f..dead4e93 100644
--- a/deckhand/engine/secret_substitution.py
+++ b/deckhand/engine/secret_substitution.py
@@ -28,6 +28,9 @@ class SecretSubstitution(object):
     substituted or "forward-repalced" into the YAML file. The end result is a
     YAML file containing all necessary secrets to be handed off to other
     services.
+
+    :param data: YAML data that requires secrets to be validated, merged and
+        consolidated.
     """
 
     def __init__(self, data):
@@ -86,6 +89,8 @@ class SecretSubstitution(object):
                     'missing from the YAML data: "%s".' % (
                         missing_attr, dest, sub_data))
 
+        # TODO(fm577c): Query Deckhand API to validate "src" values.
+
     def _multi_getattr(self, multi_key, substitutable_data):
         """Iteratively check for nested attributes in the YAML data.
 
diff --git a/deckhand/tests/unit/engine/test_secret_substitution.py b/deckhand/tests/unit/engine/test_secret_substitution.py
index cf470fe3..3277ac68 100644
--- a/deckhand/tests/unit/engine/test_secret_substitution.py
+++ b/deckhand/tests/unit/engine/test_secret_substitution.py
@@ -37,6 +37,19 @@ class TestSecretSubtitution(testtools.TestCase):
         self.data = yaml.safe_load(yaml_data)
 
     def _corrupt_data(self, key):
+        """Corrupt test data to check that pre-validation works.
+
+        Corrupt data by removing a key from the document. Each key must
+        correspond to a value that is a dictionary.
+
+        :param key: The document key to be removed. The key can have the
+            following formats:
+                * 'data' => document.pop('data')
+                * 'metadata.name' => document['metadata'].pop('name')
+                * 'metadata.substitutions.0.dest' =>
+                   document['metadata']['substitutions'][0].pop('dest')
+        :returns: Corrupted YAML data.
+        """
         corrupted_data = copy.deepcopy(self.data)
 
         if '.' in key:
@@ -53,9 +66,10 @@ class TestSecretSubtitution(testtools.TestCase):
         else:
             corrupted_data.pop(key)
 
-        return yaml.safe_dump(corrupted_data)
+        return self._format_data(corrupted_data)
 
     def _format_data(self, data=None):
+        """Re-formats dict data as YAML to pass to ``SecretSubstitution``."""
         if data is None:
             data = self.data
         return yaml.safe_dump(data)