From 21e481e1d67af3d573a0a1a6d32f9d2711fdcc34 Mon Sep 17 00:00:00 2001
From: Leah Wasser <leah.wasser@colorado.edu>
Date: Tue, 23 Nov 2021 09:50:57 -0700
Subject: [PATCH] DOCS: update docstrings on several modules

---
 abcclassroom/auth.py   | 22 +++++++++++++++++++++-
 abcclassroom/git.py    | 14 ++++++++++++++
 abcclassroom/github.py | 16 +++++++++++++++-
 3 files changed, 50 insertions(+), 2 deletions(-)

diff --git a/abcclassroom/auth.py b/abcclassroom/auth.py
index e11a55b..f1cc4a5 100644
--- a/abcclassroom/auth.py
+++ b/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"}
diff --git a/abcclassroom/git.py b/abcclassroom/git.py
index 71d3a6a..aa262b1 100644
--- a/abcclassroom/git.py
+++ b/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:
diff --git a/abcclassroom/github.py b/abcclassroom/github.py
index 4361b4a..fe8b43d 100644
--- a/abcclassroom/github.py
+++ b/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)