Added and revised function docstrings for util.py (#1130)

* Added and revised function docstrings for util.py

* added credentials to gitignore

* Addressed request changes by reverting/modifying function docstrings to match the format used in client.py

CHANGELOG.md

@@ -10,6 +10,7 @@ Add your changes below.
 
 ### Added
 - Added unit tests for queue functions
+- Added detailed function docstrings to 'util.py', including descriptions and special sections that lists arguments, returns, and raises.
 
 ### Fixed
 -

spotipy/util.py

@@ -1,4 +1,4 @@
-""" Shows a user's playlists (need to be authenticated via oauth) """
+""" Shows a user's playlists. This needs to be authenticated via OAuth. """
 
 __all__ = ["CLIENT_CREDS_ENV_VARS", "prompt_for_user_token"]
 
@@ -35,21 +35,18 @@ def prompt_for_user_token(
         "    spotipy.Spotify(auth_manager=auth_manager)",
         DeprecationWarning
     )
-    """ prompts the user to login if necessary and returns
+    """Prompt the user to login if necessary and returns a user token
-        the user token suitable for use with the spotipy.Spotify
+       suitable for use with the spotipy.Spotify constructor.
-        constructor
 
         Parameters:
-
+            - username - the Spotify username. (optional)
-         - username - the Spotify username (optional)
+            - scope - the desired scope of the request. (optional)
-         - scope - the desired scope of the request (optional)
+            - client_id - the client ID of your app. (required)
-         - client_id - the client id of your app (required)
+            - client_secret - the client secret of your app. (required)
-         - client_secret - the client secret of your app (required)
+            - redirect_uri - the redirect URI of your app. (required)
-         - redirect_uri - the redirect URI of your app (required)
+            - cache_path - path to location to save tokens. (required)
-         - cache_path - path to location to save tokens (optional)
+            - oauth_manager - OAuth manager object. (optional)
-         - oauth_manager - Oauth manager object (optional)
+            - show_dialog - If True, a login prompt always shows or defaults to False. (optional)
-         - show_dialog - If true, a login prompt always shows (optional, defaults to False)
-
     """
     if not oauth_manager:
         if not client_id:
@@ -107,6 +104,12 @@ def prompt_for_user_token(
 
 
 def get_host_port(netloc):
+    """ Split the network location string into host and port and returns a tuple
+        where the host is a string and the the port is an integer.
+
+        Parameters:
+            - netloc - a string representing the network location.
+    """
     if ":" in netloc:
         host, port = netloc.split(":", 1)
         port = int(port)
@@ -118,6 +121,14 @@ def get_host_port(netloc):
 
 
 def normalize_scope(scope):
+    """Normalize the scope to verify that it is a list or tuple. A string
+    input will split the string by commas to create a list of scopes.
+    A list or tuple input is used directly.
+
+    Parameters:
+        - scope - a string representing scopes separated by commas,
+                  or a list/tuple of scopes.
+    """
     if scope:
         if isinstance(scope, str):
             scopes = scope.split(',')
@@ -126,7 +137,7 @@ def normalize_scope(scope):
         else:
             raise Exception(
                 "Unsupported scope value, please either provide a list of scopes, "
-                "or a string of scopes separated by commas"
+                "or a string of scopes separated by commas."
             )
         return " ".join(sorted(scopes))
     else: