[Documentation][file] Standarize docstrings on module-utils/file.py (#1362)

* Standarize docstrings on modules/file.py to numpy style

* Add changelog fragment

* Standarize numpy style

* Fixed year

---------

Co-authored-by: Fernando Flores <[email protected]>

Author: IsaacVRey

changelogs/fragments/1362-update-docstring-file.yml

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

plugins/module_utils/file.py

@@ -1,4 +1,4 @@
-# Copyright (c) IBM Corporation 2020
+# Copyright (c) IBM Corporation 2020, 2024
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -22,11 +22,15 @@ def _get_dir_mode(path):
     """Get the mode of an existing directory.
     Defaults to 0600 if directory not found.
 
-    Arguments:
-        path {str} -- The absolute path to retrieve directory mode from.
+    Parameters
+    ----------
+    path : str
+        The absolute path to retrieve directory mode from.
 
-    Returns:
-        int -- The mode of the directory.
+    Returns
+    -------
+    int
+        The mode of the directory.
     """
     mask = S_IREAD | S_IWRITE
     if os.path.isdir(path):
@@ -41,11 +45,15 @@ def make_dirs(path, mode_from=None):
     If path does not end in "/", assumes end of path is
     a file.
 
-    Arguments:
-        path {str} -- The path to ensure subdirectories are created for.
+    Parameters
+    ----------
+    path : str
+        The path to ensure subdirectories are created for.
 
-    Keyword Arguments:
-        mode_from {str} -- Path to existing dir to retrieve the mode from.
+    Keyword Parameters
+    ------------------
+    mode_from : str
+        Path to existing dir to retrieve the mode from.
         Mode will be used for new directories. (default: {None})
     """
     mode = _get_dir_mode(mode_from) if mode_from is not None else S_IREAD | S_IWRITE