From 128c00a2f4d6abdfca7dd4cb31c3f70ca371bc3a Mon Sep 17 00:00:00 2001
From: Ankit Chaurasia <8670962+sunank200@users.noreply.github.com>
Date: Wed, 25 Jun 2025 00:14:13 +0545
Subject: [PATCH 1/2] doc: document @task.run_if, @task.skip_if, and
 provider-specific task hooks

fix: update setup_task and teardown_task docstrings
---
 task-sdk/docs/api.rst                         |  9 +++++++
 .../definitions/decorators/setup_teardown.py  | 25 +++++++++++++++++++
 2 files changed, 34 insertions(+)

diff --git a/task-sdk/docs/api.rst b/task-sdk/docs/api.rst
index 8605b234792a6..7cecf00279064 100644
--- a/task-sdk/docs/api.rst
+++ b/task-sdk/docs/api.rst
@@ -33,6 +33,15 @@ Decorators
 .. autoapifunction:: airflow.sdk.dag
 .. autoapifunction:: airflow.sdk.task
 
+Sub-decorators on ``task``:
+
+- ``@task.run_if(condition, skip_message=None)``
+  Run the task only if the given condition is met; otherwise the task is skipped.  The condition is a callable
+  that receives the task execution context and returns either a boolean or a tuple ``(bool, message)``.
+- ``@task.skip_if(condition, skip_message=None)``
+  Skip the task if the given condition is met, raising a skip exception with an optional message.
+- Provider-specific task decorators under ``@task.<provider>``, e.g. ``@task.python``, ``@task.docker``, etc., dynamically loaded from registered providers.
+
 .. autoapifunction:: airflow.sdk.task_group
 
 .. autoapifunction:: airflow.sdk.setup
diff --git a/task-sdk/src/airflow/sdk/definitions/decorators/setup_teardown.py b/task-sdk/src/airflow/sdk/definitions/decorators/setup_teardown.py
index 8df62d12aaadb..c53a84ea71bc8 100644
--- a/task-sdk/src/airflow/sdk/definitions/decorators/setup_teardown.py
+++ b/task-sdk/src/airflow/sdk/definitions/decorators/setup_teardown.py
@@ -35,6 +35,18 @@
 
 
 def setup_task(func: Callable) -> Callable:
+    """
+    Decorate a function to mark it as a setup task.
+
+    A setup task runs before all other tasks in its DAG or TaskGroup context
+    and can perform initialization or resource preparation.
+
+    Example::
+
+        @setup
+        def initialize_context(...):
+            ...
+    """
     # Using FunctionType here since _TaskDecorator is also a callable
     if isinstance(func, types.FunctionType):
         func = python_task(func)
@@ -45,6 +57,19 @@ def setup_task(func: Callable) -> Callable:
 
 
 def teardown_task(_func=None, *, on_failure_fail_dagrun: bool = False) -> Callable:
+    """
+    Decorate a function to mark it as a teardown task.
+
+    A teardown task runs after all main tasks in its DAG or TaskGroup context.
+    If ``on_failure_fail_dagrun=True``, a failure in teardown will mark the DAG run as failed.
+
+    Example::
+
+        @teardown(on_failure_fail_dagrun=True)
+        def cleanup(...):
+            ...
+    """
+
     def teardown(func: Callable) -> Callable:
         # Using FunctionType here since _TaskDecorator is also a callable
         if isinstance(func, types.FunctionType):

From 08585eb35a95f60327375545a6f9e59c7ee51d3c Mon Sep 17 00:00:00 2001
From: Ankit Chaurasia <8670962+sunank200@users.noreply.github.com>
Date: Wed, 25 Jun 2025 00:33:36 +0545
Subject: [PATCH 2/2] Change sub decorators to task-decorators

---
 task-sdk/docs/api.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/task-sdk/docs/api.rst b/task-sdk/docs/api.rst
index 7cecf00279064..8c6fc526b5f5f 100644
--- a/task-sdk/docs/api.rst
+++ b/task-sdk/docs/api.rst
@@ -33,7 +33,7 @@ Decorators
 .. autoapifunction:: airflow.sdk.dag
 .. autoapifunction:: airflow.sdk.task
 
-Sub-decorators on ``task``:
+Task Decorators:
 
 - ``@task.run_if(condition, skip_message=None)``
   Run the task only if the given condition is met; otherwise the task is skipped.  The condition is a callable