improve docs

solara/website/pages/api/task.py

@@ -2,6 +2,28 @@
 
 A global way to run code in the background, with the UI available to the user. This is useful for long running tasks, like downloading data.
 
+The task decorator turns a function or coroutine function into a task object.
+A task is a callable that will run the function in a separate thread for normal functions
+or a asyncio task for a coroutine function.
+
+The task object will execute the function only once per virtual kernel. When called multiple times,
+the a previously started run will be cancelled.
+
+The Result object is wrapped as a reactive variable in the `.result` attribute of the task object, so to access the underlying value, use `.result.value`.
+
+The return value of the function is available as the `.value` attribute of the result object, meaning it's accessible as `.result.value.value`. While
+a demonstation of composability, this is not very readable, so you can also use `.value` property to access the return value of the function.
+
+## Task object
+
+ * `.result`: A reactive variable wrapping the result object.
+ * `.value`: Alias for `.result.value.value`
+ * `.error`: Alias for `.result.value.error`
+ * `.state`: Alias for `.result.value.state`
+ * `.cancel()`: Cancels the task.
+
+
+
 """
 import solara
 import solara.autorouting

solara/website/pages/api/use_task.py

@@ -2,7 +2,9 @@
 
 A hook that allows you to run code in the background, with the UI available to the user. This is useful for long running tasks, like downloading data.
 
-Note that unlike with the `@task` decorator, the result is not globally shared, but only available to the component that called `use_task`.
+Unlike with the [`@task`](/api/task) decorator, the result is not globally shared, but only available to the component that called `use_task`.
+
+Note that unlike the [`@task`](/api/task) decorator, the task is invoked immediately, and the hook will return the Result object, instead of the task object.
 
 """
 import solara