Merge pull request #24 from github/docs

Improve docstrings for functions to be more complete

contributor_stats.py

@@ -12,7 +12,17 @@
 
 
 class ContributorStats:
-    """A class to represent a contributor_stats object"""
+    """
+    A class to represent a contributor_stats object correlating to a single contributors stats.
+
+    Attributes:
+        username (str): The username of the contributor
+        new_contributor (bool): Whether the contributor is new or returning
+        avatar_url (str): The url of the contributor's avatar
+        contribution_count (int): The number of contributions the contributor has made
+        commit_url (str): The url of the contributor's commits
+
+    """
 
     def __new__(cls, *args, **kwargs):  # pylint: disable=unused-argument
         """Create a new contributor_stats object"""
@@ -55,15 +65,32 @@ def __eq__(self, other) -> bool:
 
 
 def is_new_contributor(username: str, returning_contributors: list) -> bool:
-    """Check if the contributor is new or returning"""
+    """
+    Check if the contributor is new or returning
+
+    Args:
+        username (str): The username of the contributor
+        returning_contributors (list): A list of ContributorStats objects
+            representing contributors who have contributed to the repository
+            before the start_date
+
+    """
     for contributor in returning_contributors:
         if username in contributor.username:
             return True
     return False
 
 
 def merge_contributors(contributors: list) -> list:
-    """Merge contributors with the same username"""
+    """
+    Merge contributors with the same username from multiple repositories.
+
+    Args:
+        contributors (list): A list of lists of ContributorStats objects
+
+    Returns:
+        merged_contributors (list): A list of ContributorStats objects with no duplicate usernames
+    """
     merged_contributors = []
     for contributor_list in contributors:
         for contributor in contributor_list:

contributors.py

@@ -55,7 +55,19 @@ def get_all_contributors(
     end_date: str,
     github_connection: object,
 ):
-    """Get all contributors from the organization or repository"""
+    """
+    Get all contributors from the organization or repository
+
+    Args:
+        organization (str): The organization for which the contributors are being listed.
+        repository (str): The repository for which the contributors are being listed.
+        start_date (str): The start date of the date range for the contributor list.
+        end_date (str): The end date of the date range for the contributor list.
+        github_connection (object): The authenticated GitHub connection object from PyGithub
+
+    Returns:
+        all_contributors (list): A list of ContributorStats objects
+    """
     repos = []
     if organization:
         repos = github_connection.organization(organization).repositories()
@@ -81,7 +93,17 @@ def get_contributors(
     start_date: str,
     end_date: str,
 ):
-    """Get contributors from a single repository and filter by start end dates"""
+    """
+    Get contributors from a single repository and filter by start end dates if present.
+
+    Args:
+        repo (object): The repository object from PyGithub
+        start_date (str): The start date of the date range for the contributor list.
+        end_date (str): The end date of the date range for the contributor list.
+
+    Returns:
+        contributors (list): A list of ContributorStats objects
+    """
     all_repo_contributors = repo.contributors()
     contributors = []
     for user in all_repo_contributors: