[Documentation][validation] Add docstrings to module_utils/validation…

….py (#1336)

* Add docstrings to module_utils/validation.py

* Create changelog fragment

* Modify google style to numpy

* Standarize numpy style

changelogs/fragments/1336-update-docstring-validation.yml

@@ -0,0 +1,3 @@
+trivial:
+  - validation - Updated docstrings to numpy style for visual aid to developers.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/1336).

plugins/module_utils/validation.py

@@ -22,11 +22,25 @@
 
 
 def validate_safe_path(path):
-    """
-    This function is implemented to validate against path traversal attack
+    """This function is implemented to validate against path traversal attack
     when using os.path.join function.
 
     In this action plugin, path is on the controller.
+
+    Parameters
+    ----------
+    path : str
+        A file's path.
+
+    Returns
+    -------
+    str
+        The introduced path.
+
+    Raises
+    ------
+    DirectoryTraversalError
+        User does not have access to a directory.
     """
     if not os.path.isabs(path):
         real_path = os.path.realpath(path)
@@ -39,6 +53,18 @@ def validate_safe_path(path):
 
 
 class DirectoryTraversalError(Exception):
+    """User does not have access to a directory.
+
+    Parameters
+    ----------
+    path : str
+        Directory path.
+
+    Attributes
+    ----------
+    msg : str
+        Human readable string describing the exception.
+    """
     def __init__(self, path):
         self.msg = "Detected directory traversal, user does not have access to {0}".format(path)
         super().__init__(self.msg)