From a072cf33f5708be646b67f442b9e1b177285d605 Mon Sep 17 00:00:00 2001
From: mathiasg <mathiasg@stanford.edu>
Date: Fri, 17 Nov 2023 11:31:17 -0500
Subject: [PATCH] DOC: Add docstrings to common operations

---
 migas/operations.py | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/migas/operations.py b/migas/operations.py
index 142074c..7bce666 100644
--- a/migas/operations.py
+++ b/migas/operations.py
@@ -73,6 +73,33 @@ class AddBreadcrumb(Operation):
 
 @telemetry_enabled
 def add_breadcrumb(project: str, project_version: str, **kwargs) -> dict:
+    """
+    Send a breadcrumb with usage information to the telemetry server.
+
+    - `project` - application name
+    - `project_version` - application version
+
+    Optional keyword arguments
+    - `language` (auto-detected)
+    - `language_version` (auto-detected)
+    - process-specific
+        - `status`
+        - `status_desc`
+        - `error_type`
+        - `error_desc`
+    - context-specific
+        - `user_id` (auto-generated)
+        - `session_id`
+        - `user_type`
+        - `platform` (auto-detected)
+        - `container` (auto-detected)
+        - `is_ci` (auto-detected)
+
+    Returns
+    -------
+    response: dict
+        keys: success
+    """
     query = AddBreadcrumb.generate_query(
         project=project, project_version=project_version, **kwargs
     )
@@ -167,6 +194,17 @@ class CheckProject(Operation):
 
 @telemetry_enabled
 def check_project(project: str, project_version: str, **kwargs) -> dict:
+    """
+    Check a project version with the latest available.
+
+    This can be used to check for the most recent version, as well as if
+    the `project_version` has been flagged by developers.
+
+    Returns
+    -------
+    response: dict
+        keys: success, flagged, latest, message
+    """
     query = CheckProject.generate_query(project=project, project_version=project_version, **kwargs)
     logger.debug(query)
     _, response = request(Config.endpoint, query=query)