From 3b9a74c0cbbc8a1549f6f4f46410c16094acaa3e Mon Sep 17 00:00:00 2001
From: KernelDeimos <eric.alex.dube@gmail.com>
Date: Thu, 20 Jun 2024 00:00:59 -0400
Subject: [PATCH] doc: meta documentation and common pattern tracking

---
 doc/contributors/comment_prefixes.md | 28 ++++++++++++++++++++++++++++
 doc/devmeta/track-comments.md        | 24 ++++++++++++++++++++++++
 2 files changed, 52 insertions(+)
 create mode 100644 doc/contributors/comment_prefixes.md
 create mode 100644 doc/devmeta/track-comments.md

diff --git a/doc/contributors/comment_prefixes.md b/doc/contributors/comment_prefixes.md
new file mode 100644
index 00000000..084da611
--- /dev/null
+++ b/doc/contributors/comment_prefixes.md
@@ -0,0 +1,28 @@
+# Comment Prefixes
+
+Comments have prefixes using
+[Conventional: Comments](https://conventionalcomments.org/)
+as a **loose** guideline, and using this markdown file as a
+the actual guideline.
+
+This document will be updated on an _as-needed_ basis.
+
+## The rules
+
+- A comment line always looks like this:
+  - A whitespace character
+  - Optional prefix matching `/[a-z-]+\([a-z-]a+\):/`
+  - A whitespace character
+  - The comment
+- Formalized prefixes must follow the rules below
+- Any other prefix can be used. After some uses it
+  might be good to formalize it, but that's not a hard rule.
+
+## Formalized prefixes
+
+- `todo:` is interchangable with the famous `TODO:`, **except:**
+  when lowercase (`todo:`) it can include a scope: `todo(security):`.
+- `track:` is used to track common patterns.
+  - Anything written after `track:` must be registered in
+    [track-comments.md](../devmeta/track-comments.md)
+
diff --git a/doc/devmeta/track-comments.md b/doc/devmeta/track-comments.md
new file mode 100644
index 00000000..5244284d
--- /dev/null
+++ b/doc/devmeta/track-comments.md
@@ -0,0 +1,24 @@
+# Track Comments
+
+Comments beginning with `// track:`. See
+[comment_prefixes.md](../contributors/comment_prefixes.md)
+
+## Track Comment Registry
+
+- `track: type check`:
+  A condition that's used to check the type of an imput.
+- `track: bounds check`:
+  A condition that's used to check the bounds of an array
+  or other list-like entity.
+- `track: ruleset`
+  A series of conditions that early-return or `continue`
+- `track: object description in comment`
+  A comment above the creation of some object which
+  could potentially have a `description` property.
+  This is especially relevant if the object is stored
+  in some kind of registry where multiple objects
+  could be listed in the console.
+- `track: slice a prefix`
+  A common pattern where a prefix string is "sliced off"
+  of another string to obtain a significant value, such
+  as an indentifier.