rename vars so intent is clearer, add doc, use constants

src/docs.mts

@@ -6,18 +6,41 @@ import flatmap from "unist-util-flatmap";
 import { globby } from "globby";
 import { join, dirname } from "path";
 import { exec } from "child_process";
+// @ts-ignore
 import prettier from "prettier";
 
-const verify = process.argv.includes("--verify");
+const SOURCE_DOCS_DIR = 'src/docs/';
+const FINAL_DOCS_DIR = 'docs/';
+const AUTOGENERATED_TEXT =
+  "# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit the corresponding file in src/docs.";
+
+const verifyOnly = process.argv.includes("--verify");
 const git = process.argv.includes("--git");
-let fileChanged = false;
+
-// Possible Improvement: combine with lint-staged to only copy files that have changed
+let filesWereChanged = false;
+
+
+/**
+ * Given a source file name and path, return the documentation destination full path and file name
+ * Create the destination path if it does not already exist.
+ * Possible Improvement: combine with lint-staged to only copy files that have changed
+ *
+ * @param file {string} name of the file (including full path)
+ * @returns {string} name of the file with the path changed from src/docs to docs
+ */
 const prepareOutFile = (file: string): string => {
-  const outFile = join("docs", file.replace("src/docs/", ""));
+  const outFile = join(FINAL_DOCS_DIR, file.replace(SOURCE_DOCS_DIR, ""));
   mkdirSync(dirname(outFile), { recursive: true });
   return outFile;
 };
 
+/**
+ * Verify that a file was changed and (potentially) write the new contents out to the file. Log a message to the console
+ * If the file was not changed, do nothing. (No message is logged to the console.)
+ *
+ * @param file {string} name of the file that will be verified
+ * @param content {string} new contents for the file
+ */
 const verifyAndCopy = (file: string, content?: string) => {
   const outFile = prepareOutFile(file);
   const existingBuffer = existsSync(outFile) ? readFileSync(outFile) : Buffer.from("#NEW FILE#");
@@ -27,12 +50,22 @@ const verifyAndCopy = (file: string, content?: string) => {
     return;
   }
   console.log(`File changed: ${outFile}`);
-  fileChanged = true;
+  filesWereChanged = true;
-  if (!verify) {
+  if (!verifyOnly) {
     writeFileSync(outFile, newBuffer);
   }
 };
 
+/**
+ * Transform a markdown file and write the transformed file to the directory for published documentation
+ *   1. add a `mermaid-example` block before every `mermaid` or `mmd` block
+ *      On the docsify site (one place where the documentation is published), this will show the code used for the mermaid diagram
+ *   2. add the text that says the file is automatically generated
+ *   3. use prettier to format the file
+ *   Verify that the file has been changed and write out the changes
+ *
+ * @param file {string} name of the file that will be verified
+ */
 const transform = (file: string) => {
   const doc = readFileSync(file, "utf8");
   const ast: Root = remark.parse(doc);
@@ -46,9 +79,9 @@ const transform = (file: string) => {
     return [c, Object.assign({}, c, { lang: "mermaid" })];
   });
 
-  const transformed = `# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. Please edit corresponding file in src/docs.\n${remark.stringify(
+  // Add the AUTOGENERATED_TEXT to the start of the file
-    out
+  const transformed = `${AUTOGENERATED_TEXT}\n${remark.stringify(out)}`;
-  )}`;
+
   verifyAndCopy(
     file,
     prettier.format(transformed, {
@@ -69,8 +102,8 @@ const transform = (file: string) => {
   nonMDFiles.forEach((file) => {
     verifyAndCopy(file);
   });
-  if (fileChanged) {
+  if (filesWereChanged) {
-    if (verify) {
+    if (verifyOnly) {
       console.log(
         "Changes detected in files in `docs`. Please run `yarn docs:build` after making changes to 'src/docs' to update the `docs` folder."
       );