From 2754ffafe67e7b6e0fa60b1a45ec64319435dc63 Mon Sep 17 00:00:00 2001
From: Jean <git@viscogliosi-pate.com>
Date: Sun, 26 Jan 2025 21:17:52 -0800
Subject: [PATCH] Adding function descriptions to replace-words.js

---
 src/replace-words.js | 21 +++++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

diff --git a/src/replace-words.js b/src/replace-words.js
index 0f0a1d3..e9084d5 100644
--- a/src/replace-words.js
+++ b/src/replace-words.js
@@ -3,6 +3,7 @@ const verbsIrregular = require('english-verbs-irregular/dist/verbs.json');
 const verbsGerunds = require('english-verbs-gerunds/dist/gerunds.json');
 const verbsData = verbsHelper.mergeVerbsData(verbsIrregular, verbsGerunds);
 
+/* Replaces verbs, point-of-view, name, pronouns, and "also" terms */
 function replaceAll() {
   browser.storage.local.get(null, (options) => {
     const hostname = window.location.hostname;
@@ -35,11 +36,13 @@ function replaceAll() {
   });
 }
 
+/* Replaces all instances of "Y/n" with the user's name */
 function replaceName(options) {
   const search_term = /\by\/n\b|\(y\/n\)|\[y\/n\]/ig;
   walk(document.body, search_term, options["name"], directMethod);
 }
 
+/* Replaces all verb keys */
 function replaceVerbs(options) {
   const isPluralThird = options.pov == "third" && getPronouns(options.preset, options.other).plurality == "plural";
   if (isPluralThird) {
@@ -51,6 +54,7 @@ function replaceVerbs(options) {
   walk(document.body, search_term, options, verbMethod);
 }
 
+/* Replaces all pronoun keys */
 /* This could be made faster if I give premade regexp expressions for each, but I don't want to do that! */
 function replacePronouns(options) {
   let pronouns = getPronouns(options.preset, options.other);
@@ -65,6 +69,7 @@ function replacePronouns(options) {
   replacePronounSet("Prn/n", "prn/n", pronouns["noun-child"]);
 }
 
+/* Gets pronouns based on the provided key (or user input) */
 function getPronouns(key, other) {
   switch (key) {
     case "she":
@@ -151,11 +156,13 @@ function getPronouns(key, other) {
   }
 }
 
+/* Replaces pronoun keys in capital and lowercase with their equivalent pronouns */
 function replacePronounSet(keyCapital, key, pronoun) {
   escapeAndReplace(keyCapital, capitalize(pronoun), true);
   escapeAndReplace(key, pronoun, true);
 }
 
+/* Replaces all point-of-view keys */
 function replacePov(options) {
   let pronouns;
   if (options.pov == "third") {
@@ -180,6 +187,7 @@ function replacePov(options) {
   replacePronounSet("Pov/r", "pov/r", pronouns["reflexive"]);
 }
 
+/* Replaces plural point-of-view keys */
 function replacePlv(options) {
   let pronouns = getPronouns(options.pov + "-plural", null);
   replacePronounSet("Plv/s", "plv/s", pronouns["subjective"]);
@@ -189,12 +197,14 @@ function replacePlv(options) {
   replacePronounSet("Plv/r", "plv/r", pronouns["reflexive"]);
 }
 
+/* Replaces additional terms specified by the user */
 function replaceAlso(options) {
   Object.entries(options.also).forEach(([key, value]) => {
     escapeAndReplace(key, value, true);
   });
 }
 
+/* Turns a term into regexp format and uses that to replace it */
 function escapeAndReplace(search_term, replace_value, case_sensitive) {
   let search_term_escaped = search_term.replace(/[\-\[\]\/\{\}\(\)\*\+\?\.\\\^\$\|]/g, "\\$&");
   const flags = case_sensitive ? "g" : "ig"
@@ -208,6 +218,7 @@ function escapeAndReplace(search_term, replace_value, case_sensitive) {
   walk(document.body, search_term_regexp, replace_value, directMethod);
 }
 
+/* Traverses a node and its children to run the provided replacement method */
 function walk(node, search_term, replace_value, replaceMethod) {
   if (node.contentEditable == "true" || node.type == "textarea" || node.type == "input") { return; }
   let child, next;
@@ -227,11 +238,13 @@ function walk(node, search_term, replace_value, replaceMethod) {
   }
 }
 
+/* Replaces all of the provided terms in a node */
 function directMethod(node, search_term, replace_value) {
   node.nodeValue = node.nodeValue.replaceAll(search_term, replace_value);
 }
 
-//TODO are "options" here named comprehensibly
+/* Replaces all verbs, not used for third-person plural */
+/* TODO Is the "options" variable here readable? It's not replace_value and that seems bad */
 function verbMethod(node, search_term, options) {
   let match = node.nodeValue.match(search_term);
   if (match == null) { return; }
@@ -242,6 +255,8 @@ function verbMethod(node, search_term, options) {
   verbMethod(node, search_term, options);
 }
 
+/* Replaces all verbs, used only for third-person plural */
+/* TODO This is meant to be able to replace in both subject-object and object-subject order, but it's only the first for now. */
 function pluralThirdVerbMethod(node, search_term, options) {
   let match = node.nodeValue.match(search_term);
   if (match == null) { return; }
@@ -268,11 +283,13 @@ function pluralThirdVerbMethod(node, search_term, options) {
   pluralThirdVerbMethod(node, search_term, options);
 }
 
+/* Returns the input word, capitalized */
 function capitalize(word) {
   return word.charAt(0).toUpperCase() + word.slice(1);
 }
 
-// TODO figure out plv for this
+/* Determines the index for point-of-view to be used when conjugating verbs */
+/* TODO Did I ever implement third-person plural? */
 function getPovIndex(options) {
   switch (options.pov) {
     case "first":