From 9ef585e1a4478b0a30b67b3614bb6a3c096b730e Mon Sep 17 00:00:00 2001
From: Jordan Woods <13803242+jorwoods@users.noreply.github.com>
Date: Sun, 10 Nov 2024 06:56:58 -0600
Subject: [PATCH] docs: task docstrings

---
 tableauserverclient/models/task_item.py       | 30 +++++++
 .../server/endpoint/tasks_endpoint.py         | 78 +++++++++++++++++++
 2 files changed, 108 insertions(+)

diff --git a/tableauserverclient/models/task_item.py b/tableauserverclient/models/task_item.py
index fa6f782b..8d2492ae 100644
--- a/tableauserverclient/models/task_item.py
+++ b/tableauserverclient/models/task_item.py
@@ -9,6 +9,36 @@
 
 
 class TaskItem:
+    """
+    Represents a task item in Tableau Server. To create new tasks, see Schedules.
+
+    Parameters
+    ----------
+    id_ : str
+        The ID of the task.
+
+    task_type : str
+        Type of task. See TaskItem.Type for possible values.
+
+    priority : int
+        The priority of the task on the server.
+
+    consecutive_failed_count : int
+        The number of consecutive times the task has failed.
+
+    schedule_id : str, optional
+        The ID of the schedule that the task is associated with.
+
+    schedule_item : ScheduleItem, optional
+        The schedule item that the task is associated with.
+
+    last_run_at : datetime, optional
+        The last time the task was run.
+
+    target : Target, optional
+        The target of the task. This can be a workbook or a datasource.
+    """
+
     class Type:
         ExtractRefresh = "extractRefresh"
         DataAcceleration = "dataAcceleration"
diff --git a/tableauserverclient/server/endpoint/tasks_endpoint.py b/tableauserverclient/server/endpoint/tasks_endpoint.py
index eb82c43b..e1e95041 100644
--- a/tableauserverclient/server/endpoint/tasks_endpoint.py
+++ b/tableauserverclient/server/endpoint/tasks_endpoint.py
@@ -31,6 +31,24 @@ def __normalize_task_type(self, task_type: str) -> str:
     def get(
         self, req_options: Optional["RequestOptions"] = None, task_type: str = TaskItem.Type.ExtractRefresh
     ) -> tuple[list[TaskItem], PaginationItem]:
+        """
+        Returns information about tasks on the specified site.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#list_extract_refresh_tasks
+
+        Parameters
+        ----------
+        req_options : RequestOptions, optional
+            Options for the request, such as filtering, sorting, and pagination.
+
+        task_type : str, optional
+            The type of task to query. See TaskItem.Type for possible values.
+
+        Returns
+        -------
+        tuple[list[TaskItem], PaginationItem]
+
+        """
         if task_type == TaskItem.Type.DataAcceleration:
             self.parent_srv.assert_at_least_version("3.8", "Data Acceleration Tasks")
 
@@ -45,6 +63,20 @@ def get(
 
     @api(version="2.6")
     def get_by_id(self, task_id: str) -> TaskItem:
+        """
+        Returns information about the specified task.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#get_extract_refresh_task
+
+        Parameters
+        ----------
+        task_id : str
+            The ID of the task to query.
+
+        Returns
+        -------
+        TaskItem
+        """
         if not task_id:
             error = "No Task ID provided"
             raise ValueError(error)
@@ -59,6 +91,21 @@ def get_by_id(self, task_id: str) -> TaskItem:
 
     @api(version="3.19")
     def create(self, extract_item: TaskItem) -> TaskItem:
+        """
+        Creates a custom schedule for an extract refresh on Tableau Cloud. For
+        Tableau Server, use the Schedules endpoint to create a schedule.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#create_cloud_extract_refresh_task
+
+        Parameters
+        ----------
+        extract_item : TaskItem
+            The extract refresh task to create.
+
+        Returns
+        -------
+        TaskItem
+        """
         if not extract_item:
             error = "No extract refresh provided"
             raise ValueError(error)
@@ -70,6 +117,20 @@ def create(self, extract_item: TaskItem) -> TaskItem:
 
     @api(version="2.6")
     def run(self, task_item: TaskItem) -> bytes:
+        """
+        Runs the specified extract refresh task.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_jobs_tasks_and_schedules.htm#run_extract_refresh_task
+
+        Parameters
+        ----------
+        task_item : TaskItem
+            The task to run.
+
+        Returns
+        -------
+        bytes
+        """
         if not task_item.id:
             error = "Task item missing ID."
             raise MissingRequiredFieldError(error)
@@ -86,6 +147,23 @@ def run(self, task_item: TaskItem) -> bytes:
     # Delete 1 task by id
     @api(version="3.6")
     def delete(self, task_id: str, task_type: str = TaskItem.Type.ExtractRefresh) -> None:
+        """
+        Deletes the specified extract refresh task on Tableau Server or Tableau Cloud.
+
+        REST API: https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#delete_extract_refresh_task
+
+        Parameters
+        ----------
+        task_id : str
+            The ID of the task to delete.
+
+        task_type : str, default TaskItem.Type.ExtractRefresh
+            The type of task to query. See TaskItem.Type for possible values.
+
+        Returns
+        -------
+        None
+        """
         if task_type == TaskItem.Type.DataAcceleration:
             self.parent_srv.assert_at_least_version("3.8", "Data Acceleration Tasks")