From 20b21190b6d02a9125e97b90403fb4b1f00a5cf4 Mon Sep 17 00:00:00 2001
From: Jakob K <bluefireolymp@gmail.com>
Date: Fri, 23 Apr 2021 22:24:00 +0000
Subject: [PATCH] Add task documentation

---
 guide/docs/extensions/tasks.md | 36 ++++++++++++++++++++++++++++++++++
 guide/mkdocs.yml               |  1 +
 2 files changed, 37 insertions(+)
 create mode 100644 guide/docs/extensions/tasks.md

diff --git a/guide/docs/extensions/tasks.md b/guide/docs/extensions/tasks.md
new file mode 100644
index 00000000..a1cbeda4
--- /dev/null
+++ b/guide/docs/extensions/tasks.md
@@ -0,0 +1,36 @@
+## The general task function
+
+The task function is very powerful. It connects almost all kinds of Spigot tasks and even adds additional features on top.
+
+You define its behaviour by providing the following parameters (all are optional and have default values):
+
+| Parameter        | Description   |
+| ---------------- | ------------- |
+| sync | if the runnable should run sync (true) or async (false) |
+| delay | the delay (in ticks) until the first execution of the task |
+| period | at which interval (in ticks) the task should be repeated |
+| howOften | how many times the task should be executed - null for infinite execution |
+| endCallback | code that should always be executed when the runnable ends |
+| safe | if the endCallback of the runnable should always be executed, even if the server shuts down or the runnable ends prematurely |
+| runnable | the runnable which should be executed each repetition |
+
+The body of task function is the `runnable` parameter. This runnable provides an instance of `KSpigotRunnable`, which inherits from `BukkitRunnable`, but adds counters on top. These counters are:
+
+- `counterUp`
+- `counterDownToOne`
+- `counterDownToZero`
+
+An example would be:
+
+```kotlin
+task(
+    sync = false,
+    delay = 25,
+    period = 20,
+    howOften = 5
+) {
+    println(it.counterUp) // starting from zero
+    println(it.counterDownToOne) // starting from howOften
+    println(it.counterDownToZero) // starting from howOften - 1
+}
+```
diff --git a/guide/mkdocs.yml b/guide/mkdocs.yml
index bfff117f..48d9f556 100644
--- a/guide/mkdocs.yml
+++ b/guide/mkdocs.yml
@@ -33,3 +33,4 @@ nav:
       - Entrypoint to your plugin: setup/entrypoint.md
   - Extensions:
       - Event listener: extensions/listener.md
+      - Tasks: extensions/tasks.md