[Documentation][zos_lineinfile] Add and standarize docstrings on modules/zos_lineinfile.py

changelogs/fragments/1355-update-docstring-zos_lineinfile.yml

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

plugins/modules/zos_lineinfile.py

@@ -295,33 +295,45 @@
 
 
 def present(src, line, regexp, ins_aft, ins_bef, encoding, first_match, backrefs, force):
-    """Replace a line with the matching regex pattern
-    Insert a line before/after the matching pattern
-    Insert a line at BOF/EOF
-
-    Arguments:
-        src: {str} -- The z/OS USS file or data set to modify.
-        line: {str} -- The line to insert/replace into the src.
-        regexp: {str} -- The regular expression to look for in every line of the src.
-            If regexp matches, ins_aft/ins_bef will be ignored.
-        ins_aft: {str} -- Insert the line after matching '*regex*' pattern or EOF.
-            choices:
-                - EOF
-                - '*regex*'
-        ins_bef: {str} -- Insert the line before matching '*regex*' pattern or BOF.
-            choices:
-                - BOF
-                - '*regex*'
-        encoding: {str} -- Encoding of the src.
-        first_match: {bool} -- Take the first matching regex pattern.
-        backrefs: {bool} -- Back reference
-        force: {bool} -- force for modify a member part of a task in execution
-
-    Returns:
-        str -- Information in JSON format. keys:
-            cmd: {str} -- dsed shell command
-            found: {int} -- Number of matching regex pattern
-            changed: {bool} -- Indicates if the source was modified.
+    """Replace a line with the matching regex pattern.
+    Insert a line before/after the matching pattern.
+    Insert a line at BOF/EOF.
+
+    Parameters
+    ----------
+    src : str
+        The z/OS USS file or data set to modify.
+    line : str
+        The line to insert/replace into the src.
+    regexp : str
+        The regular expression to look for in every line of the src.
+        If regexp matches, ins_aft/ins_bef will be ignored.
+    ins_aft : str
+        Insert the line after matching '*regex*' pattern or EOF.
+        choices:
+          - EOF
+          - '*regex*'
+    ins_bef : str
+        Insert the line before matching '*regex*' pattern or BOF.
+        choices:
+          - BOF
+          - '*regex*'
+    encoding : str
+        Encoding of the src.
+    first_match : bool
+        Take the first matching regex pattern.
+    backrefs : bool
+        Back reference.
+    force : bool
+        force for modify a member part of a task in execution.
+
+    Returns
+    -------
+    str
+        Information in JSON format. keys:
+        cmd {str} -- dsed shell command
+        found {int} -- Number of matching regex pattern
+        changed {bool} -- Indicates if the source was modified.
     """
     return datasets.lineinfile(
         src,
@@ -339,33 +351,74 @@ def present(src, line, regexp, ins_aft, ins_bef, encoding, first_match, backrefs
 
 
 def absent(src, line, regexp, encoding, force):
-    """Delete lines with matching regex pattern
-
-    Arguments:
-        src: {str} -- The z/OS USS file or data set to modify.
-        line: {str} -- The line to be deleted in the src. If line matches,
-            regexp will be ignored.
-        regexp: {str} -- The regular expression to look for in every line of the src.
-        encoding: {str} -- Encoding of the src.
-        force: {bool} -- force for modify a member part of a task in execution
-
-    Returns:
-        str -- Information in JSON format. keys:
-            cmd: {str} -- dsed shell command
-            found: {int} -- Number of matching regex pattern
-            changed: {bool} -- Indicates if the source was modified.
+    """Delete lines with matching regex pattern.
+
+    Parameters
+    ----------
+    src : str
+        The z/OS USS file or data set to modify.
+    line : str
+        The line to be deleted in the src. If line matches,
+        regexp will be ignored.
+    regexp : str
+        The regular expression to look for in every line of the src.
+    encoding : str
+        Encoding of the src.
+    force : bool
+        Force for modify a member part of a task in execution.
+
+    Returns
+    -------
+    str
+        Information in JSON format. keys:
+        cmd {str} -- dsed shell command
+        found {int} -- Number of matching regex pattern
+        changed {bool} -- Indicates if the source was modified.
     """
     return datasets.lineinfile(src, line, regex=regexp, encoding=encoding, state=False, debug=True, force=force)
 
 
 def quotedString(string):
+    """Add escape if string was quoted.
+
+    Parameters
+    ----------
+    string : str
+        Given string.
+
+    Returns
+    -------
+    str
+        The string with the quote marks replaced.
+    """
     # add escape if string was quoted
     if not isinstance(string, str):
         return string
     return string.replace('"', '\\\"')
 
 
 def main():
+    """Initialize the module.
+
+    Raises
+    ------
+    fail_json
+        Parameter verification failed.
+    fail_json
+        regexp is required with backrefs=true.
+    fail_json
+        line is required with state=present.
+    fail_json
+        One of line or regexp is required with state=absent.
+    fail_json
+        Source does not exist.
+    fail_json
+        Data set type is NOT supported.
+    fail_json
+        Creating backup has failed.
+    fail_json
+        dsed return content is NOT in json format.
+    """
     module_args = dict(
         src=dict(
             type='str',