DOCS: update docstrings on several modules

abcclassroom/auth.py

@@ -127,6 +127,15 @@ def _get_login_code(client_id):
     First part of the Device Flow workflow. Asks user to visit a URL and
     enter the provided code. Waits for user to hit RETURN to continue.
     Returns the device code.
+
+    Parameters
+    ----------
+    client_id : str
+        String representing the ID for the abc-classroom bot.
+    Returns
+    -------
+    device_code : str
+        The device code for the response.
     """
 
     # make the device call
@@ -161,8 +170,19 @@ def _get_login_code(client_id):
 def _poll_for_status(client_id, device_code):
     """Polls API to see if user entered the device code
 
-    This is the second step of the Device Flow. Returns an access token, and
+    This is the second step of the device flow. Returns an access token, and
     also writes the token to a file in the user's home directory.
+
+        Parameters
+    ----------
+    client_id : str
+        A string representing the client code for the abc-classroom bot.
+    device_code : str
+        The device code returned from the API for the user's machine / device.
+    Returns
+    -------
+    Access token provided by GitHub.
+    Writes the token to a file in the user's home directory
     """
 
     header = {"Content-Type": "application/json", "Accept": "application/json"}

abcclassroom/git.py

@@ -99,6 +99,20 @@ def clone_repo(organization, repo, dest_dir):
 
     Raises RuntimeError if ssh keys not set up correctly, or if git clone
     fails for other reasons.
+
+    Parameters
+    ----------
+    organization : string
+        A string with the name of the organization to clone from
+    repo : string
+        A string with the name of the GitHub repository to clone
+    dest_dir : string
+        Path to the destination directory
+        TODO: is this a full path, path object or string - what format is
+        dest_dir in
+    Returns
+    -------
+    Cloned github repository in the destination directory specified.
     """
 
     try:

abcclassroom/github.py

@@ -11,7 +11,21 @@
 
 
 def remote_repo_exists(org, repository, token=None):
-    """Check if the remote repository exists for the organization."""
+    """Check if the remote repository exists for the organization.
+
+    Parameters
+    ----------
+    org : string
+        Name of the organization where the repo lives on GitHub.
+    repository : string
+        Name of the repository within the organization to clone.
+    token : string (default None)
+        Token value required for authentication
+    Returns
+    -------
+    Boolean True if exists, False / raises exception if it doesn't exist.
+
+    """
 
     try:
         g = gh3.login(token=token)