Add some docs 🤔

.github/workflows/docs.yml

@@ -0,0 +1,20 @@
+name: Build and Deploy
+on: [push]
+permissions:
+  contents: write
+jobs:
+  build-and-deploy:
+    concurrency: ci-${{ github.ref }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v4
+      - name: Install and Build 🔧
+        run: |
+          cd docs
+          npm install
+          npm run build
+      - name: Deploy 🚀
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: docs/dist

docs/.gitignore

@@ -0,0 +1,9 @@
+.DS_Store
+dist
+node_modules
+_lib
+tsconfig.tsbuildinfo
+tsconfig.*.tsbuildinfo
+vocs.config.ts.timestamp-*
+.vercel
+.vocs

docs/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "zig-aio",
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vocs dev",
+    "build": "vocs build",
+    "preview": "vocs preview"
+  },
+  "dependencies": {
+    "@types/react": "latest",
+    "react": "latest",
+    "react-dom": "latest",
+    "typescript": "latest",
+    "vocs": "latest"
+  }
+}

docs/pages/aio-dynamic.mdx

@@ -0,0 +1,49 @@
+# AIO API
+
+## Dynamic IO
+
+In case the amount of IO operations isn't known ahead of time the dynamic api can be used.
+
+### Initializing Dynamic instance
+
+Creating a Dynamic instance requires an allocator and upper bound for non-completed operations.
+The instance allocates only during the `init`, and frees the memory during `deinit`.
+Same allocator must be used in `deinit` that was used in `init`.
+
+```zig
+const max_operations = 32;
+var work = try Dynamic.init(std.heap.page_allocator, max_operations);
+defer work.deinit(std.heap.page_allocator);
+```
+
+### Queuing operations
+
+It is possible to queue either single or multiple operations just like with the immediate api.
+The call to queue is atomic, if the call fails, none of the operations will be actually performed.
+
+```zig
+// Multiple operations
+try work.queue(.{
+    aio.Read{...},
+    aio.Write{...},
+    aio.Fsync{...},
+});
+
+// Single operation
+try work.queue(aio.Timeout{...});
+```
+
+### Completing operations
+
+It is possible to complete the operations either in blocking or non-blocking fashion.
+The blocking mode will wait for at least one operation to complete.
+The non-blocking always returns immediately even if no operations were completed.
+The call to complete returns `aio.CompletionResult` containing the number of operations that were completed
+and the number of errors that occured.
+
+```zig
+// blocks until at least 1 operation completes
+const res = try work.complete(.blocking);
+// returns immediately
+const res = try work.complete(.nonblocking);
+```

docs/pages/aio-immediate.mdx

@@ -0,0 +1,62 @@
+# AIO API
+
+## Immediate IO
+
+For immediate blocking IO, `zig-aio` provides the following functions in the `aio` module.
+
+### Perform a single operation
+
+Completes a single operation, the call blocks until it's complete.
+Returns error of the operation if the operation failed.
+Returns `void` if there was no error.
+
+```zig
+try aio.single(aio.Write{.file = f, .buffer = "contents"});
+```
+
+### Perform multiple operations
+
+`zig-aio` provides two methods for batching IO operations.
+
+#### Using multi
+
+Completes a list of operations immediately, blocks until complete
+Returns `error.SomeOperationFailed` if any operation failed
+Returns `void` if there were no errors.
+
+```zig
+var my_buffer: [1024]u8 = undefined;
+var my_len: usize = undefined;
+
+try aio.multi(.{
+    aio.Write{.file = f, .buffer = "contents", .link_next = true},
+    aio.Read{.file = f, .buffer = &my_buffer, .out_read = &my_len},
+});
+```
+
+The `.link_next` field of operation can be used to link the operation to the next operation.
+When linking operations, the next operation won't start until the previous operation is complete.
+
+#### Using batch
+
+Batch is similar to multi, but it will not return `error.SomeOperationFailed` in case any of the operations fail.
+Instead batch returns `aio.CompletionResult` which contains the number of operations that was completed, and number of
+errors that occured. To find out which operations failed, errors have to be stored somewhere by setting the `.out_error`
+field of the operation. The batch call may still fail in implementation defined ways, such as running out of system resources.
+
+```zig
+var my_buffer: [1024]u8 = undefined;
+var my_len: usize = undefined;
+var write_error: std.posix.WriteError = undefined;
+var read_error: std.posix.ReadError = undefined;
+
+const res = try aio.batch(.{
+    aio.Write{.file = f, .buffer = "contents", .out_error = &write_error, .link_next = true},
+    aio.Read{.file = f, .buffer = &my_buffer, .out_error = &read_error, .out_read = &my_len},
+});
+
+if (res.num_errors > 0) {
+    if (write_error != error.Success) @panic("write failed");
+    if (read_error != error.Success) @panic("read failed");
+}
+```