From 8fdf8f6ca6cfdc3c20ac863c1b205dcfe365894e Mon Sep 17 00:00:00 2001
From: kansi <kansi13@gmail.com>
Date: Thu, 2 Nov 2017 18:02:11 +0530
Subject: [PATCH] Added docstrings

---
 bigchaindb/common/utils.py | 43 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/bigchaindb/common/utils.py b/bigchaindb/common/utils.py
index 35163f14..e472f380 100644
--- a/bigchaindb/common/utils.py
+++ b/bigchaindb/common/utils.py
@@ -52,6 +52,22 @@ def deserialize(data):
 
 
 def validate_txn_obj(obj_name, obj, key, validation_fun):
+    """Validates value associated to `key` in `obj` by applying
+       `validation_fun`.
+
+        Args:
+            obj_name (str): name for `obj` being validated.
+            obj (dict): dictonary object.
+            key (str): key to be validated in `obj`.
+            validation_fun (function): function used to validate the value
+            of `key`.
+
+        Returns:
+            None: indicates validation successfull
+
+        Raises:
+            ValidationError: `validation_fun` will raise this error on failure
+    """
     backend = bigchaindb.config['database']['backend']
 
     if backend == 'mongodb':
@@ -60,6 +76,20 @@ def validate_txn_obj(obj_name, obj, key, validation_fun):
 
 
 def validate_all_keys(obj_name, obj, validation_fun):
+    """Validates all (nested) keys in `obj` by using `validation_fun`
+
+        Args:
+            obj_name (str): name for `obj` being validated.
+            obj (dict): dictonary object.
+            validation_fun (function): function used to validate the value
+            of `key`.
+
+        Returns:
+            None: indicates validation successfull
+
+        Raises:
+            ValidationError: `validation_fun` will raise this error on failure
+    """
     for key, value in obj.items():
         validation_fun(obj_name, key)
         if type(value) is dict:
@@ -68,6 +98,19 @@ def validate_all_keys(obj_name, obj, validation_fun):
 
 
 def validate_key(obj_name, key):
+    """Check if `key` contains ".", "$" or null characters
+       https://docs.mongodb.com/manual/reference/limits/#Restrictions-on-Field-Names
+
+        Args:
+            obj_name (str): object name to use when raising exception
+            key (str): key to validated
+
+        Returns:
+            None: indicates validation successfull
+
+        Raises:
+            ValidationError: raise execption incase of regex match.
+    """
     if re.search(r'^[$]|\.|\x00', key):
         error_str = ('Invalid key name "{}" in {} object. The '
                      'key name cannot contain characters '