From 9dc9c1d79dbf2771fda72cd4145c66e3f49b70a2 Mon Sep 17 00:00:00 2001
From: Bauke <me@bauke.xyz>
Date: Sat, 29 Jul 2023 21:12:14 +0200
Subject: [PATCH] Add documentation to tomlFrontmatter function.

---
 .bauke/scripts/utilities.ts | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/.bauke/scripts/utilities.ts b/.bauke/scripts/utilities.ts
index 514a96c..444c66f 100644
--- a/.bauke/scripts/utilities.ts
+++ b/.bauke/scripts/utilities.ts
@@ -33,6 +33,30 @@ export async function runAndReturnStdout(
   return new TextDecoder().decode(stdout);
 }
 
+/**
+ * Parse the TOML frontmatter of a string, throwing an error if there is no
+ * frontmatter or returning the parsed frontmatter with the remaining text
+ * string. For example the following snippet:
+ *
+ * ```txt
+ * ---toml
+ * example_value = "Hello, world!"
+ * ---
+ *
+ * # Markdown
+ * ```
+ *
+ * Will return:
+ *
+ * ```js
+ * [
+ *   {
+ *     example_value: "Hello, world!"
+ *   },
+ *   "# Markdown\n"
+ * ]
+ * ```
+ */
 export function tomlFrontmatter<T>(
   data: string,
 ): [T, string] {