docs: add full docstrings and fix sync task SSE notifications

Added Args/Returns docstrings to all public classes, methods, and
functions. Fixed TaskStore._notify_change to use call_soon_threadsafe
so task_log() entries from sync tasks trigger live dashboard updates.

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

Author: Attakay78

docs/api/task-log.md

@@ -10,7 +10,7 @@ from fastapi_taskflow import task_log
 def task_log(message: str) -> None
 ```
 
-Emits a timestamped log entry from within a running task. The entry is appended to the task's `logs` list and becomes immediately visible in the live dashboard under the **Logs** tab.
+Emits a timestamped log entry from within a running task. The entry is appended to the task's `logs` list and becomes immediately visible in the live dashboard under the **Logs** tab. Works in both sync and async task functions.
 
 ## Parameters
 

docs/changelog.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## v0.4.1
+
+- Added docstrings with `Args:` and `Returns:` descriptions to all public classes, methods, and functions across the codebase.
+- Fixed `TaskStore._notify_change` to use `call_soon_threadsafe` so `task_log()` entries from sync tasks trigger live dashboard updates correctly.
+
+---
+
 ## v0.4.0
 
 ### File logging

docs/guide/logging.md

@@ -27,11 +27,19 @@ When a task retries, a `--- Retry N ---` separator is inserted automatically bet
 2026-04-07T10:00:01 Sending to user@example.com
 ```
 
-## Async tasks
+## Sync and async tasks
 
-`task_log()` works the same in async tasks:
+`task_log()` works the same in both sync and async tasks. Sync tasks run in a
+thread pool, and log entries are safely handed back to the event loop so the
+dashboard updates in real time.
 
 ```python
+@task_manager.task(retries=1)
+def generate_report(user_id: int) -> None:
+    task_log(f"Starting report for user {user_id}")
+    data = fetch_data(user_id)
+    task_log("Report complete")
+
 @task_manager.task(retries=1)
 async def process_webhook(payload: dict) -> None:
     task_log(f"Received event: {payload['type']}")

fastapi_taskflow/__init__.py

@@ -1,14 +1,12 @@
-"""
-fastapi-taskflow
-======================
+"""fastapi-taskflow: decorator-driven background tasks with retries and a live dashboard.
 
-A lightweight decorator-driven task manager that upgrades FastAPI
-``BackgroundTasks`` with retries, visibility, and SQLite persistence —
-without changing how developers enqueue tasks.
+Upgrades FastAPI ``BackgroundTasks`` with retries, status tracking, and SQLite
+persistence without changing how you enqueue tasks.
 
 Quick start::
 
-    from fastapi_taskflow import TaskManager, TaskAdmin
+    from fastapi import Depends, FastAPI
+    from fastapi_taskflow import TaskAdmin, TaskManager
 
     task_manager = TaskManager(snapshot_db="tasks.db")
 
@@ -17,7 +15,7 @@ def send_email(address: str) -> None:
         ...
 
     app = FastAPI()
-    TaskAdmin(app, task_manager)                  # mounts /tasks routes + lifecycle
+    TaskAdmin(app, task_manager)  # mounts /tasks routes and manages lifecycle
 
     @app.post("/signup")
     def signup(email: str, tasks=Depends(task_manager.get_tasks)):

fastapi_taskflow/admin.py

@@ -18,11 +18,9 @@
 
 
 class TaskAdmin:
-    """
-    Mounts the task observability routes onto a FastAPI application and
-    manages the snapshot scheduler lifecycle (if enabled on the TaskManager).
+    """Mounts task observability routes onto a FastAPI app and manages the scheduler lifecycle.
 
-    All work is done in the constructor — no need to keep a reference::
+    All setup happens in the constructor, so you don't need to keep a reference::
 
         task_manager = TaskManager(snapshot_db="tasks.db")
         TaskAdmin(app, task_manager)
@@ -32,18 +30,19 @@ class TaskAdmin:
         TaskAdmin(app, task_manager, auth=[("alice", "pw1"), ("bob", "pw2")])
         TaskAdmin(app, task_manager, auth=MyBackend(), secret_key="...", token_expiry=3600)
 
-        # Custom mount path:
+        # Custom mount prefix:
         TaskAdmin(app, task_manager, path="/admin/tasks")
 
-    Routes exposed (relative to *path*):
+    Routes mounted (relative to *path*):
 
-    * ``GET {path}``                  — JSON list of all tasks
-    * ``GET {path}/metrics``          — JSON aggregated statistics
-    * ``GET {path}/{task_id}``        — JSON single task detail
-    * ``GET {path}/dashboard``        — live dashboard (HTML)
-    * ``GET {path}/auth/login``       — login page (when auth is configured)
-    * ``POST {path}/auth/login``      — process login (when auth is configured)
-    * ``GET {path}/auth/logout``      — logout (when auth is configured)
+    * ``GET  {path}``               -- JSON list of all tasks
+    * ``GET  {path}/metrics``       -- aggregated statistics
+    * ``GET  {path}/{task_id}``     -- single task detail
+    * ``POST {path}/{task_id}/retry`` -- retry a failed/interrupted task
+    * ``GET  {path}/dashboard``     -- live HTML dashboard
+    * ``GET  {path}/auth/login``    -- login page (when *auth* is set)
+    * ``POST {path}/auth/login``    -- process login form
+    * ``GET  {path}/auth/logout``   -- clear session cookie
     """
 
     def __init__(
@@ -58,6 +57,30 @@ def __init__(
         secret_key: str | None = None,
         poll_interval: float = 30.0,
     ) -> None:
+        """
+        Args:
+            app: The FastAPI application to mount routes onto.
+            task_manager: The :class:`~fastapi_taskflow.manager.TaskManager`
+                whose tasks will be exposed.
+            path: URL prefix for all mounted routes. Default is ``"/tasks"``.
+            display_func_args: When ``True``, task arguments are included in
+                the dashboard task list. Disable if args may contain sensitive data.
+            auto_install: When ``True``, calls :meth:`~fastapi_taskflow.manager.TaskManager.install`
+                on *app* so all ``BackgroundTasks`` routes receive managed injection
+                automatically. Equivalent to calling ``task_manager.install(app)``
+                before creating ``TaskAdmin``.
+            auth: Enables login-protected access to the dashboard and API.
+                Accepts a ``(username, password)`` tuple, a list of such tuples,
+                or a :class:`~fastapi_taskflow.auth.TaskAuthBackend` instance for
+                custom authentication logic. ``None`` (default) means no auth.
+            token_expiry: Session token lifetime in seconds. Default is 86400 (24 hours).
+                Only relevant when *auth* is set.
+            secret_key: HMAC secret used to sign session tokens. A secure random
+                key is generated automatically when *auth* is set and this is omitted.
+                Pass an explicit value to keep sessions valid across restarts.
+            poll_interval: How often (seconds) the dashboard polls for updates when
+                SSE is unavailable. Default is 30 seconds.
+        """
         self._task_manager = task_manager
 
         if auto_install:
@@ -110,6 +133,11 @@ def __init__(
             app.router.on_shutdown.append(self._close_file_logger)
 
     async def _on_startup(self) -> None:
+        """Restore persisted task history and re-dispatch any pending tasks.
+
+        Registered as a FastAPI startup event handler when a snapshot backend
+        is configured. Runs before the app begins accepting requests.
+        """
         scheduler = self._task_manager._scheduler
         assert scheduler is not None
         await scheduler.load()
@@ -118,6 +146,12 @@ async def _on_startup(self) -> None:
         scheduler.start()
 
     async def _on_shutdown(self) -> None:
+        """Stop the background flush loop and persist any remaining tasks.
+
+        Registered as a FastAPI shutdown event handler. Flushes completed tasks
+        to the backend, and if ``requeue_pending=True``, saves unfinished tasks
+        so they can be re-dispatched on the next startup.
+        """
         scheduler = self._task_manager._scheduler
         assert scheduler is not None
         scheduler.stop()
@@ -126,5 +160,6 @@ async def _on_shutdown(self) -> None:
             await scheduler.flush_pending()
 
     async def _close_file_logger(self) -> None:
+        """Flush and close file log handlers on shutdown."""
         if self._task_manager.file_logger is not None:
             self._task_manager.file_logger.close()

fastapi_taskflow/auth.py

@@ -82,6 +82,19 @@ def authenticate_user(self, username: str, password: str) -> bool:
 def resolve_backend(
     auth: Union[tuple, list, TaskAuthBackend, None],
 ) -> TaskAuthBackend | None:
+    """Convert the *auth* parameter accepted by :class:`~fastapi_taskflow.admin.TaskAdmin`
+    into a :class:`TaskAuthBackend`, or return ``None`` for no authentication.
+
+    Args:
+        auth: A ``(username, password)`` tuple, a list of such tuples, an existing
+            :class:`TaskAuthBackend` instance, or ``None``.
+
+    Returns:
+        A :class:`TaskAuthBackend` instance, or ``None`` if *auth* is ``None``.
+
+    Raises:
+        TypeError: If *auth* is not one of the accepted types.
+    """
     if auth is None:
         return None
     if isinstance(auth, TaskAuthBackend):
@@ -111,6 +124,15 @@ def _b64url_decode(s: str) -> bytes:
 
 
 def create_token(secret_key: str, expiry: int) -> str:
+    """Create a signed HMAC-SHA256 JWT with an expiry claim.
+
+    Args:
+        secret_key: Secret used to sign the token.
+        expiry: Token lifetime in seconds from now.
+
+    Returns:
+        A dot-separated ``header.payload.signature`` token string.
+    """
     header = _b64url_encode(b'{"alg":"HS256","typ":"JWT"}')
     body = _b64url_encode(json.dumps({"exp": int(time.time()) + expiry}).encode())
     signing_input = f"{header}.{body}"
@@ -119,6 +141,17 @@ def create_token(secret_key: str, expiry: int) -> str:
 
 
 def verify_token(secret_key: str, token: str) -> bool:
+    """Verify a token created by :func:`create_token`.
+
+    Checks both the HMAC signature and the ``exp`` claim.
+
+    Args:
+        secret_key: The same secret used when the token was created.
+        token: The token string to verify.
+
+    Returns:
+        ``True`` if the signature is valid and the token has not expired.
+    """
     try:
         parts = token.split(".")
         if len(parts) != 3:
@@ -143,7 +176,15 @@ def verify_token(secret_key: str, token: str) -> bool:
 
 
 def make_api_guard(secret_key: str):
-    """Returns a FastAPI ``Depends`` that raises 401 for invalid/missing tokens."""
+    """Return a FastAPI ``Depends`` that rejects requests with invalid or missing tokens.
+
+    Args:
+        secret_key: The secret used to verify the session token cookie.
+
+    Returns:
+        A ``Depends`` instance that raises ``HTTP 401`` when the cookie is
+        absent or the token signature/expiry check fails.
+    """
 
     def _guard(request: Request) -> None:
         token = request.cookies.get(COOKIE_NAME, "")
@@ -285,6 +326,18 @@ def create_auth_router(
     token_expiry: int,
     prefix: str,
 ) -> APIRouter:
+    """Build the login/logout router for the dashboard.
+
+    Args:
+        backend: The auth backend used to validate credentials.
+        secret_key: HMAC secret for signing session tokens.
+        token_expiry: Token lifetime in seconds.
+        prefix: URL prefix (e.g. ``"/tasks"``) prepended to all auth routes.
+
+    Returns:
+        An :class:`~fastapi.APIRouter` with ``GET /auth/login``,
+        ``POST /auth/login``, and ``GET /auth/logout`` routes.
+    """
     router = APIRouter(prefix=prefix, include_in_schema=False)
     login_path = f"{prefix}/auth/login"
     dashboard_path = f"{prefix}/dashboard"

fastapi_taskflow/backends/__init__.py

@@ -1,21 +1,22 @@
-"""
-Pluggable snapshot backends for fastapi-taskflow.
+"""Pluggable snapshot backends for fastapi-taskflow.
+
+Built-in backends:
 
-Built-in backends
------------------
-* :class:`SqliteBackend`  — zero-dependency SQLite (default)
-* :class:`RedisBackend`   — requires ``redis[asyncio]`` (``pip install redis``)
+* :class:`SqliteBackend` -- zero-dependency, local SQLite file (default)
+* :class:`RedisBackend`  -- shared Redis store; requires ``pip install "redis[asyncio]"``
 
-Custom backends
----------------
-Subclass :class:`SnapshotBackend` and implement the four abstract methods::
+To write a custom backend, subclass :class:`SnapshotBackend` and implement
+its abstract methods::
 
     from fastapi_taskflow.backends import SnapshotBackend
     from fastapi_taskflow.models import TaskRecord
 
     class MyBackend(SnapshotBackend):
         async def save(self, records: list[TaskRecord]) -> int: ...
         async def load(self) -> list[TaskRecord]: ...
+        async def save_pending(self, records: list[TaskRecord]) -> int: ...
+        async def load_pending(self) -> list[TaskRecord]: ...
+        async def clear_pending(self) -> None: ...
         async def close(self) -> None: ...
 
     task_manager = TaskManager(snapshot_backend=MyBackend(...))