koffi 2.9.1 → 2.10.0

package/doc/flaat/normal.css

@@ -0,0 +1,335 @@
+/* Copyright (C) 2024  Niels Martignène <niels.martignene@protonmail.com>
+
+   Permission is hereby granted, free of charge, to any person obtaining a copy of
+   this software and associated documentation files (the “Software”), to deal in
+   the Software without restriction, including without limitation the rights to use,
+   copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+   Software, and to permit persons to whom the Software is furnished to do so,
+   subject to the following conditions:
+
+   The above copyright notice and this permission notice shall be included in all
+   copies or substantial portions of the Software.
+
+   THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+   OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+   NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+   HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+   WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+   FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+   OTHER DEALINGS IN THE SOFTWARE. */
+
+html {
+    --top_height: 90px;
+    --top_padding: 6px;
+    --small_height: 80px;
+
+    height: 100%;
+    scroll-padding-top: calc(var(--top_height) + 10px);
+}
+
+body {
+    min-height: 100%;
+    margin: 0;
+    padding: 0;
+
+    font-family: 'Open Sans', sans-serif;
+    font-size: 17px;
+    line-height: 1.5;
+
+    background: white;
+    color: #383838;
+
+    display: flex;
+    flex-direction: column;
+}
+
+a {
+    color: var(--primary_color, #383838);
+    cursor: pointer;
+    text-decoration: none;
+}
+a:hover { text-decoration: underline; }
+a:has(> img) { text-decoration: none !important; }
+
+#top {
+    position: sticky;
+    top: 0;
+    background: white;
+    z-index: 9;
+    border-bottom: 2px solid white;
+    transition: border-bottom-color 0.4s ease;
+}
+#top.border { border-bottom-color: #383838; }
+#top menu {
+    position: sticky;
+    top: 0;
+    box-sizing: border-box;
+    max-width: 1200px;
+    height: var(--top_height);
+    box-sizing: border-box;
+    margin: 0 auto;
+    padding: var(--top_padding);
+    overflow: visible;
+    z-index: 1;
+    display: flex;
+    align-items: center;
+    gap: 10px;
+}
+#top li {
+    position: relative;
+    list-style-type: none;
+    padding-left: 8px;
+    border-left: 2px solid rgba(0, 0, 0, 0);
+}
+#top li a {
+    color: #383838;
+    text-decoration: none;
+}
+#top li > div a.category {
+    cursor: default;
+    pointer-events: none;
+}
+#top li > a {
+    display: block;
+    border-bottom: 1px solid #383838;
+    text-transform: uppercase;
+}
+#top li > a:hover, #top li.active > a {
+    margin-bottom: -1px;
+    border-bottom: 2px solid var(--primary_color);
+}
+#top li > a.active { font-weight: bold; }
+#top li > div { display: none; }
+.nojs #top li:has(> div):hover, #top li:has(> div).active { border-left-color: var(--primary_color); }
+.nojs #top li:has(> div):hover > a, #top li:has(> div).active > a {
+    margin-bottom: 1px;
+    border-bottom: none;
+}
+.nojs #top li:hover > div, #top li.active > div {
+    position: absolute;
+    margin-top: 0px;
+    margin-left: -10px;
+    width: 220px;
+    padding: 12px 1em 10px 1em;
+    display: flex;
+    flex-direction: column;
+    background: white;
+    border-left: 2px solid var(--primary_color);
+    border-bottom: 2px solid var(--primary_color);
+}
+#top li > div > a { margin-top: 3px; }
+#top li > div > a.active { font-weight: bold; }
+#top li > div > a:hover { text-decoration: underline; }
+
+#logo {
+    height: 70%;
+    object-fit: contain;
+    margin-right: 2em;
+    transition: filter 0.4s ease;
+}
+#logo > img {
+    width: 100%;
+    height: 100%;
+    object-fit: contain;
+}
+
+#side menu {
+    margin: 0;
+    padding: 8px;
+    width: 224px;
+    box-sizing: border-box;
+
+    position: fixed;
+    left: calc(50% + 360px);
+    top: calc(var(--top_height) + 34px);
+
+    background: #fdfdfd;
+    border: 2px solid #383838;
+}
+#side li { list-style-type: none; }
+#side a {
+    display: block;
+    padding: 1px;
+    color: #383838;
+    text-decoration: none;
+}
+#side a:hover { text-decoration: underline; }
+#side a.active { font-weight: bold; }
+#side a.lv1 { padding-left: 12px; }
+#side a.lv2 { padding-left: 27px; }
+#side a.lv3 { padding-left: 42px; }
+#side a.lv4 { padding-left: 57px; }
+#side a.lv5 { padding-left: 72px; }
+#side a.lv6 { padding-left: 87px; }
+
+#deploy { display: none; }
+
+main {
+    flex: 1;
+    width: 100%;
+    max-width: 1200px;
+    box-sizing: border-box;
+    margin: 20px auto 0 auto;
+    padding: 0 16px 16px 16px;
+}
+#side ~ main { padding-right: 290px; }
+
+footer {
+    padding: 0.5em;
+    background: #f6f6f9;
+    display: flex;
+    gap: 1.5em;
+    align-items: center;
+    justify-content: center;
+}
+footer > img { filter: saturate(0%) brightness(0); }
+
+p { margin: 1em 0 0 0; }
+p:first-child, h1 + p, h2 + p, h3 + p { margin-top: 0; }
+
+main img { max-width: 100%; }
+
+h1 {
+    margin: 0 0 0.5em 0;
+    font-size: 1.6em;
+    text-transform: uppercase;
+    font-weight: normal;
+    color: #383838;
+    font-weight: bold;
+}
+h2 {
+    margin: 0 0 1em 0;
+    display: table;
+    padding: 2px 14px 2px 30px;
+    background: #191f22;
+    font-size: 1.2em;
+    font-weight: normal;
+    text-transform: uppercase;
+    color: white;
+}
+h3 {
+    margin: 0 0 0.8em 0;
+    display: table;
+    padding: 2px 14px 2px 40px;
+    background: #ddd;
+    font-size: 1.1em;
+    font-weight: normal;
+    font-style: italic;
+    text-transform: uppercase;
+    color: #383838;
+}
+* + h1, * + h2, * + h3 { margin-top: 1.2em; }
+
+table {
+    margin: 1em auto;
+    border-collapse: collapse;
+}
+th {
+    padding: 0.5em;
+    background: #fafafa;
+    border: 1px solid #ebebeb;
+}
+thead th { text-align: center; }
+tbody th {
+    text-align: left;
+    font-weight: normal;
+    font-style: italic;
+}
+td {
+    padding: 0.5em;
+    background: white;
+    border: 1px solid #ebebeb;
+}
+th.center, td.center { text-align: center; }
+th.right, td.right { text-align: right; }
+
+table + div.legend {
+    margin-top: calc(-1em + 2px);
+    text-align: center;
+    font-size: 0.8em;
+}
+
+.buttons {
+    margin: 1em;
+    display: flex;
+    gap: 20px;
+    justify-content: center;
+    flex-wrap: wrap;
+}
+.buttons > a {
+    display: block;
+    width: 40%;
+    min-width: 250px;
+    background: var(--secondary_color);
+    color: white;
+    padding: 0.6em 1em;
+    text-decoration: none;
+    text-align: center;
+}
+.buttons > a:hover {
+    filter: brightness(80%) contrast(150%);
+    color: white;
+}
+
+code:not(.hljs) {
+    padding: 2px 6px;
+    font-family: monospace;
+    font-size: 14px;
+    background: #eee;
+}
+pre > code:not(.hljs) {
+    padding: 0;
+    font-size: inherit;
+    background: transparent;
+}
+
+pre {
+    position: relative;
+    margin: 1em 20px;
+    padding: 0;
+    border: 1px solid #ebebeb;
+    background: #ffffff;
+    overflow: auto;
+    font-size: 12px;
+    z-index: 0;
+}
+.nojs pre { padding: 6px; }
+
+.alert {
+    margin: 1.8em 1em 1.4em 1em;
+    padding: 0.8em 1em;
+    background: #fcfcfc;
+    border-left: 3px solid var(--color);
+}
+.alert:first-child { margin-top: 0; }
+.alert > .title {
+    font-weight: bold;
+    color: var(--color);
+}
+.alert > .title::after { content: var(--text); }
+.alert.note {
+    --color: #316dca;
+    --text: 'Note';
+}
+.alert.tip {
+    --color: #347d39;
+    --text: 'Tip';
+}
+.alert.important {
+    --color: #8256d0;
+    --text: '⚠\FE0E  Important';
+}
+.alert.warning {
+    --color: #966600;
+    --text: '⚠\FE0E  Warning';
+}
+.alert.caution {
+    --color: #c93c37;
+    --text: '⚠\FE0E  Caution';
+}
+
+.footnotes {
+    margin: 2em 1em;
+    font-style: italic;
+}

package/doc/flaat/print.css

@@ -0,0 +1,30 @@
+/* Copyright (C) 2024  Niels Martignène <niels.martignene@protonmail.com>
+
+   Permission is hereby granted, free of charge, to any person obtaining a copy of
+   this software and associated documentation files (the “Software”), to deal in
+   the Software without restriction, including without limitation the rights to use,
+   copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+   Software, and to permit persons to whom the Software is furnished to do so,
+   subject to the following conditions:
+
+   The above copyright notice and this permission notice shall be included in all
+   copies or substantial portions of the Software.
+
+   THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+   OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+   NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+   HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+   WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+   FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+   OTHER DEALINGS IN THE SOFTWARE. */
+
+@media print {
+    #top { display: none; }
+    #side { display: none; }
+
+    main { padding-right: 16px !important; }
+    footer { display: none; }
+
+    h1:not(:first-child) { break-before: page; }
+}

package/doc/flaat/small.css

@@ -0,0 +1,101 @@
+/* Copyright (C) 2024  Niels Martignène <niels.martignene@protonmail.com>
+
+   Permission is hereby granted, free of charge, to any person obtaining a copy of
+   this software and associated documentation files (the “Software”), to deal in
+   the Software without restriction, including without limitation the rights to use,
+   copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
+   Software, and to permit persons to whom the Software is furnished to do so,
+   subject to the following conditions:
+
+   The above copyright notice and this permission notice shall be included in all
+   copies or substantial portions of the Software.
+
+   THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+   OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+   NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+   HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+   WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+   FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+   OTHER DEALINGS IN THE SOFTWARE. */
+
+@media screen and (max-width: 1300px) {
+    #side menu {
+        width: auto;
+        margin: 16px;
+        padding: 16px;
+        position: static;
+    }
+
+    main { padding-right: 16px !important; }
+}
+
+@media screen and (max-width: 960px) {
+    html { scroll-padding-top: calc(var(--small_height) + 10px); }
+
+    #top menu {
+        height: var(--small_height);
+        padding-left: 60px;
+        flex-direction: column;
+        gap: 0;
+        align-items: start;
+        z-index: 8;
+    }
+    #top li a {
+        font-size: 1.1em;
+        line-height: 1.6em;
+    }
+    #top li > a:hover, #top li.active > a { margin-bottom: -2px; }
+    #top li > a { border-bottom: none; }
+    .js #top li > a, .nojs #top:not(:hover) li > a { display: none; }
+    .nojs #top:hover menu, #top.active menu {
+        height: auto;
+        gap: 4px;
+    }
+    #top.active li > a, .nojs #top li.active > a { display: block !important; }
+    #top li.active > div, .nojs #top li:hover > div { position: static; }
+
+    #side a {
+        font-size: 1.1em;
+        line-height: 1.6em;
+    }
+
+    footer {
+        flex-direction: column;
+        padding: 0.5em;
+        gap: 6px;
+        text-align: center;
+    }
+    footer > img { display: none; }
+
+    #logo {
+        height: 100%;
+        margin: 0 auto;
+        transform: translate(-10px, 0);
+    }
+    .js #top.active #logo { display: none; }
+    .nojs #top:hover #logo { display: none; }
+
+    #deploy {
+        display: block !important;
+        position: fixed;
+        width: 42px;
+        height: 40px;
+        top: 10px;
+        left: 8px;
+        padding: 0;
+        background-image: url("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABYAAAAWCAYAAADEtGw7AAAAOUlEQVQ4T2O0sLD4z0ADwDhqMCxUGWkQvGAjRw2GhyztgmI0HcPTMc2CYjSDDOGygmapYtRgWKoAAGrCE+uzrIQ5AAAAAElFTkSuQmCC");
+        background-repeat: no-repeat;
+        background-position: center;
+        z-index: 999;
+        cursor: pointer;
+    }
+    .nojs #deploy { pointer-events: none; }
+
+    pre { margin: 1em 0; }
+
+    .alert {
+        margin-left: 0.4em;
+        margin-right: 0.4em;
+    }
+}

package/doc/{benchmarks.md → pages/benchmarks.md}

@@ -1,6 +1,4 @@
-# Benchmarks
-
-## Overview
+# Overview
 
 Here is a quick overview of the execution time of Koffi calls on three benchmarks, where it is compared to a theoretical ideal FFI implementation (approximated with pre-compiled static N-API glue code):
 
@@ -8,20 +6,18 @@ Here is a quick overview of the execution time of Koffi calls on three benchmark
 - The second benchmark is based on `atoi()` calls
 - The third benchmark is based on [Raylib](https://www.raylib.com/)
 
-<table style="margin: 0 auto;">
-    <tr>
-        <td><a href="_static/perf_linux_20231028.png" target="_blank"><img src="_static/perf_linux_20231028.png" alt="Linux x86_64 performance" style="width: 350px;"/></a></td>
-        <td><a href="_static/perf_windows_20231028.png" target="_blank"><img src="_static/perf_windows_20231028.png" alt="Windows x86_64 performance" style="width: 350px;"/></a></td>
-    </tr>
-</table>
+<p style="text-align: center;">
+    <a href="{{ ASSET static/perf_linux.png }}" target="_blank"><img src="{{ ASSET static/perf_linux.png }}" alt="Linux x86_64 performance" style="width: 350px;"/></a>
+    <a href="{{ ASSET static/perf_windows.png }}" target="_blank"><img src="{{ ASSET static/perf_windows.png }}" alt="Windows x86_64 performance" style="width: 350px;"/></a>
+</p>
 
 These results are detailed and explained below, and compared to node-ffi/node-ffi-napi.
 
-## Linux x86_64
+# Linux x86_64
 
 The results presented below were measured on my x86_64 Linux machine (Intel® Core™ i5-4460).
 
-### rand results
+## rand results
 
 This test is based around repeated calls to a simple standard C function `rand`, and has three implementations:
 
@@ -37,7 +33,7 @@ rand_node_ffi | 32750 ns       | x0.02                | +4576%
 
 Because rand is a pretty small function, the FFI overhead is clearly visible.
 
-### atoi results
+## atoi results
 
 This test is similar to the rand one, but it is based on `atoi`, which takes a string parameter. Javascript (V8) to C string conversion is relatively slow and heavy.
 
@@ -49,7 +45,7 @@ atoi_node_ffi | 121670 ns      | x0.008               | +11738%
 
 Because atoi is a pretty small function, the FFI overhead is clearly visible.
 
-### Raylib results
+## Raylib results
 
 This benchmark uses the CPU-based image drawing functions in Raylib. The calls are much heavier than in previous benchmarks, thus the FFI overhead is reduced. In this implementation, Koffi is compared to:
 
@@ -63,11 +59,11 @@ raylib_node_raylib | 26.3 µs        | x1.00                | (ref)
 raylib_koffi       | 28.0 µs        | x0.94                | +6%
 raylib_node_ffi    | 87.0 µs        | x0.30                | +230%
 
-## Windows x86_64
+# Windows x86_64
 
 The results presented below were measured on my x86_64 Windows machine (Intel® Core™ i5-4460).
 
-### rand results
+## rand results
 
 This test is based around repeated calls to a simple standard C function `rand`, and has three implementations:
 
@@ -83,7 +79,7 @@ rand_node_ffi | 35640 ns       | x0.02                | +4048%
 
 Because rand is a pretty small function, the FFI overhead is clearly visible.
 
-### atoi results
+## atoi results
 
 This test is similar to the rand one, but it is based on `atoi`, which takes a string parameter. Javascript (V8) to C string conversion is relatively slow and heavy.
 
@@ -97,7 +93,7 @@ atoi_node_ffi | 136890 ns      | x0.010               | +10144%
 
 Because atoi is a pretty small function, the FFI overhead is clearly visible.
 
-### Raylib results
+## Raylib results
 
 This benchmark uses the CPU-based image drawing functions in Raylib. The calls are much heavier than in the atoi benchmark, thus the FFI overhead is reduced. In this implementation, Koffi is compared to:
 
@@ -111,7 +107,7 @@ raylib_node_raylib | 27.3 µs        | x1.00                | (ref)
 raylib_koffi       | 29.8 µs        | x0.92                | +9%
 raylib_node_ffi    | 96.3 µs        | x0.28                | +253%
 
-## Running benchmarks
+# Running benchmarks
 
 Please note that all benchmark results on this page are made with Clang-built binaries.
 

package/doc/{callbacks.md → pages/callbacks.md}

@@ -1,12 +1,4 @@
-# Javascript callbacks
-
-*Changed in Koffi 2.4*
-
-```{note}
-The function `koffi.proto()` was introduced in Koffi 2.4, it was called `koffi.callback()` in earlier versions.
-```
-
-## Callback types
+# Callback types
 
 *Changed in Koffi 2.7*
 
@@ -22,8 +14,10 @@ const ExampleCallback = koffi.proto('ExampleCallback', 'void', ['int']);
 // With the prototype parser, this callback expects a double and float, and returns the sum as a double
 const AddDoubleFloat = koffi.proto('double AddDoubleFloat(double d, float f)');
 ```
+> [!NOTE]
+> The function `koffi.proto()` was introduced in Koffi 2.4, it was called `koffi.callback()` in earlier versions.
 
-For alternative [calling conventions](functions.md#calling-conventions) (such as `stdcall` on Windows x86 32-bit), you can specify as the first argument with the classic syntax, or after the return type in prototype strings, like this:
+For alternative [calling conventions](functions#calling-conventions) (such as `stdcall` on Windows x86 32-bit), you can specify as the first argument with the classic syntax, or after the return type in prototype strings, like this:
 
 ```js
 const HANDLE = koffi.pointer('HANDLE', koffi.opaque());
@@ -34,25 +28,23 @@ const EnumWindowsProc = koffi.proto('bool __stdcall EnumWindowsProc (HWND hwnd,
 const EnumWindowsProc = koffi.proto('__stdcall', 'EnumWindowsProc', 'bool', ['HWND', 'long']);
 ```
 
-```{warning}
-You have to make sure you **get the calling convention right** (such as specifying __stdcall for a Windows API callback), or your code will crash on Windows 32-bit.
-
-Before Koffi 2.7, it was *impossible to use an alternative callback calling convention with the classic syntax*. Use a prototype string or *upgrade to Koffi 2.7* to solve this limitation.
-```
+> [!WARNING]
+> You have to make sure you **get the calling convention right** (such as specifying __stdcall for a Windows API callback), or your code will crash on Windows 32-bit.
+>
+> Before Koffi 2.7, it was *impossible to use an alternative callback calling convention with the classic syntax*. Use a prototype string or *upgrade to Koffi 2.7* to solve this limitation.
 
 Once your callback type is declared, you can use a pointer to it in struct definitions, as function parameters and/or return types, or to call/decode function pointers.
 
-```{note}
-Callbacks **have changed in version 2.0**.
+> [!NOTE]
+> Callbacks **have changed in version 2.0**.
+>
+> In Koffi 1.x, callbacks were defined in a way that made them usable directly as parameter and return types, obscuring the underlying pointer.
+>
+> Now, you must use them through a pointer: `void CallIt(CallbackType func)` in Koffi 1.x becomes `void CallIt(CallbackType *func)` in version 2.0 and newer.
+>
+> Consult the [migration guide](migration) for more information.
 
-In Koffi 1.x, callbacks were defined in a way that made them usable directly as parameter and return types, obscuring the underlying pointer.
-
-Now, you must use them through a pointer: `void CallIt(CallbackType func)` in Koffi 1.x becomes `void CallIt(CallbackType *func)` in version 2.0 and newer.
-
-Consult the [migration guide](migration.md) for more information.
-```
-
-## Transient and registered callbacks
+# Transient and registered callbacks
 
 Koffi only uses predefined static trampolines, and does not need to generate code at runtime, which makes it compatible with platforms with hardened W^X migitations (such as PaX mprotect). However, this imposes some restrictions on the maximum number of callbacks, and their duration.
 
@@ -61,9 +53,9 @@ Thus, Koffi distinguishes two callback modes:
 - [Transient callbacks](#transient-callbacks) can only be called while the C function they are passed to is running, and are invalidated when it returns. If the C function calls the callback later, the behavior is undefined, though Koffi tries to detect such cases. If it does, an exception will be thrown, but this is no guaranteed. However, they are simple to use, and don't require any special handling.
 - [Registered callbacks](#registered-callbacks) can be called at any time, but they must be manually registered and unregistered. A limited number of registered callbacks can exist at the same time.
 
-You need to specify the correct [calling convention](functions.md#calling-conventions) on x86 platforms, or the behavior is undefined (Node will probably crash). Only *cdecl* and *stdcall* callbacks are supported.
+You need to specify the correct [calling convention](functions#calling-conventions) on x86 platforms, or the behavior is undefined (Node will probably crash). Only *cdecl* and *stdcall* callbacks are supported.
 
-### Transient callbacks
+## Transient callbacks
 
 Use transient callbacks when the native C function only needs to call them while it runs (e.g. qsort, progress callback, `sqlite3_exec`). Here is a small example with the C part and the JS part.
 
@@ -101,7 +93,7 @@ console.log(ret);
 //   42
 ```
 
-### Registered callbacks
+## Registered callbacks
 
 *New in Koffi 2.0 (explicit this binding in Koffi 2.2)*
 
@@ -164,15 +156,15 @@ let cb1 = koffi.register(store.get, 'IntCallback *'); // If a C function calls c
 let cb2 = koffi.register(store, store.get, 'IntCallback *'); // However in this case, this will match the store object
 ```
 
-## Special considerations
+# Special considerations
 
-### Decoding pointer arguments
+## Decoding pointer arguments
 
 *New in Koffi 2.2, changed in Koffi 2.3*
 
 Koffi does not have enough information to convert callback pointer arguments to an appropriate JS value. In this case, your JS function will receive an opaque *External* object.
 
-You can pass this value through to another C function that expects a pointer of the same type, or you can use [koffi.decode()](variables.md#decode-to-js-values) function to decode pointer arguments.
+You can pass this value through to another C function that expects a pointer of the same type, or you can use [koffi.decode()](variables#decode-to-js-values) function to decode pointer arguments.
 
 The following examples uses it to sort an array of strings in-place with the standard C function `qsort()`:
 
@@ -197,7 +189,7 @@ qsort(koffi.as(array, 'char **'), array.length, koffi.sizeof('void *'), (ptr1, p
 console.log(array); // Prints ['123', 'bar', 'foo', 'foobar']
 ```
 
-### Asynchronous callbacks
+## Asynchronous callbacks
 
 *New in Koffi 2.2.2*
 
@@ -208,11 +200,10 @@ JS execution is inherently single-threaded, so JS callbacks must run on the main
 
 In both cases, Koffi will queue the call back to JS to run on the main thread, as soon as the JS event loop has a chance to run (for example when you await a promise).
 
-```{warning}
-Be careful, you can easily get into a deadlock situation if you call a callback from a secondary thread and your main thread never lets the JS event loop run (for example, if the main thread waits for the secondary thread to finish something itself).
-```
+> [!WARNING]
+> Be careful, you can easily get into a deadlock situation if you call a callback from a secondary thread and your main thread never lets the JS event loop run (for example, if the main thread waits for the secondary thread to finish something itself).
 
-## Handling of exceptions
+# Handling of exceptions
 
 If an exception happens inside the JS callback, the C API will receive 0 or NULL (depending on the return value type).