From d4783c84c3130ba582914bf96cb0fe394ecc10fb Mon Sep 17 00:00:00 2001
From: Blaine Bublitz <blaine@arcjet.com>
Date: Tue, 3 Sep 2024 09:29:02 -0400
Subject: [PATCH] add comment describing file and error log explaining the
 format

---
 format.js | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/format.js b/format.js
index 3eb5592..9526884 100644
--- a/format.js
+++ b/format.js
@@ -1,3 +1,15 @@
+/**
+ * This file is used for checking and updating the format of the JSON file.
+ *
+ * You can check the format via `node format.js --check` and regenerate the
+ * file with the correct formatting using `node format.js --generate`.
+ *
+ * The formatting logic uses `JSON.stringify` with 2 spaces, which will keep
+ * separating commas on the same line as any closing character. This technique
+ * was chosen for simplicty and to align with common default JSON formatters,
+ * such as VSCode.
+ */
+
 const fs = require("fs");
 const path = require("path");
 
@@ -15,6 +27,7 @@ if (process.argv[2] === "--generate") {
 if (process.argv[2] === "--check") {
     if (updated !== original) {
         console.error("JSON file format is wrong. Run `node format.js --generate` to update.");
+        console.error("Format must be 2 spaces, with newlines for objects and arrays, and separating commas on the line with the previous closing character.");
         process.exit(1);
     }
 }