Fix docstring issues across multiple modules

- Fix typo 'autheticated' -> 'authenticated' in utils.py (x2)
- Add missing max_pages param to query_with_pagination docstring
- Fix inaccurate/incomplete Returns sections in commits.py, repos.py,
  org_user_info.py, licences.py
- Replace TODO placeholder in repo_contributors.py

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: rwood-97

README.md

@@ -20,6 +20,84 @@ python -m pip install .
 
 ## Usage
 
+### Authentication
+
+All functions require a GitHub personal access token with appropriate
+permissions.
+
+You will need to set it as an environment variable:
+
+```bash
+export GITHUB_TOKEN=your_token_here
+```
+
+### Functions
+
+All functions return a pandas DataFrame and accept an optional `save` argument.
+
+- Setting `save=True` will cause the data to be saved to `data/`
+- Setting `save="path/to/file.csv"` will cause the data to be saved to the
+  specified path.
+
+**Org-level data:**
+
+```python
+from github_analyser.org_user_info import get_org_members, get_org_teams
+from github_analyser.repos import get_repos
+
+# list all repositories in an organisation
+repos = get_repos("my-org")
+
+# list all members of an organisation
+members = get_org_members("my-org")
+
+# list all teams in an organisation
+teams = get_org_teams("my-org")
+```
+
+**Team and repo-level data:**
+
+```python
+from github_analyser.team_user_info import get_team_members
+from github_analyser.repo_user_info import get_repo_collaborators
+from github_analyser.repo_contributors import get_repo_contributors
+from github_analyser.commits import get_commits
+from github_analyser.issues import get_issues
+from github_analyser.pull_requests import get_pull_requests
+from github_analyser.licences import get_licences
+
+# list members of a team (use the team slug, e.g. "my-team")
+members = get_team_members("my-org", "my-team")
+
+# list collaborators of a repository
+collaborators = get_repo_collaborators("my-org", "my-repo")
+
+# get contributor commit counts for a repository
+contributors = get_repo_contributors("my-org", "my-repo")
+
+# get commits from the default branch of a repository
+commits = get_commits("my-org", "my-repo")
+
+# get issues from a repository
+issues = get_issues("my-org", "my-repo")
+
+# get pull requests from a repository
+prs = get_pull_requests("my-org", "my-repo")
+
+# get licence information for one or more repositories
+licences = get_licences("my-org", ["repo-one", "repo-two"])
+```
+
+**Saving results to CSV:**
+
+```python
+# save to the default path
+repos = get_repos("my-org", save=True)
+
+# save to a custom path
+repos = get_repos("my-org", save="output/repos.csv")
+```
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for instructions on how to contribute.

src/github_analyser/commits.py

@@ -65,11 +65,16 @@ def get_commits(
 
     Returns:
         A pandas DataFrame with the following columns:
-            - message: The commit message.
-            - additions: The number of additions in the commit.
-            - deletions: The number of deletions in the commit.
+            - id: The commit node ID.
+            - hash: The commit SHA.
+            - message: The commit message headline.
             - author: The author of the commit.
             - date: The date of the commit.
+            - changed_files: The number of files changed.
+            - additions: The number of line additions.
+            - deletions: The number of line deletions.
+            - pr_id: The ID of the associated pull request, if any.
+            - repo_id: The repository node ID.
     """
     query = _get_commits_query(org_name, repo_name)
 

src/github_analyser/licences.py

@@ -34,7 +34,7 @@ def get_licence(
         repo_name: The name of the repository.
 
     Returns:
-        A pandas Series containing the repository ID, licence name, and SPDX ID.
+        A pandas Series containing the repository name, URL, ID, licence name, and SPDX ID.
     """
     query = _get_licence_query(org_name, repo_name)
 

src/github_analyser/org_user_info.py

@@ -95,7 +95,7 @@ def get_org_teams(org_name: str, save: bool | str = False):
         specify a path. Defaults to False.
 
     Returns:
-        pandas Dataframe: One row per team, columns name.
+        pandas Dataframe: One row per team, with columns name, slug, and id.
     """
     pages = query_with_pagination(
         _get_org_teams_query(org_name),

src/github_analyser/repo_contributors.py

@@ -20,7 +20,8 @@ def get_repo_contributors(
 
     Returns:
         A pandas DataFrame with the following columns:
-            TODO
+            - login: The GitHub username of the contributor.
+            - commits: The total number of commits by the contributor.
     """
     data = request_github_rest(
         "get", f"repos/{org_name}/{repo_name}/stats/contributors"

src/github_analyser/repos.py

@@ -51,8 +51,8 @@ def get_repos(org_name: str, save: bool | str = False):
         specify a path. Defaults to False.
 
     Returns:
-        pandas Dataframe: One row per repo, columns repository name, id, url and last
-        updated date.
+        pandas Dataframe: One row per repo, with columns id, name, updated_at, url,
+        is_private, is_archived, is_fork, and languages.
     """
     pages = query_with_pagination(
         _get_repos_query(org_name),

src/github_analyser/utils.py

@@ -22,7 +22,7 @@ def request_github_rest(
     max_tries: int = 10,
     sleep_time: float = 1.0,
 ) -> Any:
-    """Run an autheticated query against the GitHub API.
+    """Run an authenticated query against the GitHub API.
 
     Assumes that the GitHub token is set in the environment variable GITHUB_TOKEN.
 
@@ -57,7 +57,7 @@ def request_github_rest(
 
 
 def request_github_graphql(payload: Any, headers: Any | None = None) -> Any:
-    """Run an autheticated query against the GitHub API.
+    """Run an authenticated query against the GitHub API.
 
     Assumes that the GitHub token is set in the environment variable GITHUB_TOKEN.
 
@@ -98,6 +98,8 @@ def query_with_pagination(
             means no pagination is done and the return value will be a list of length 1.
         cursor_variable_name: The name of the cursor variable in the query.
             "pagination_cursor" by default.
+        max_pages: The maximum number of pages to fetch. Optional, default is None
+            (fetch all pages).
 
     Returns:
         A list of responses from the GitHub API as JSON.