comment-variables 0.14.1 → 0.14.2

package/generate.example.js

@@ -0,0 +1,7 @@
+// A JavaScript file that acts as an example file for the generated Comment Variables template config. Assuming you've yet to produce your own `comments.config.js` file, use the `comment-variables compress` and `comment-variables resolve` commands to see how the following comments go back and forth from Comment Variables placeholders (`$COMMENT`) to actual comments, reversibly.
+
+// This is a comment.
+// $COMMENT#ALIAS
+// Yes.
+// This is a comment. Yes. This is a comment.
+// $COMMENT#COMMENTS#NO

package/generate.template.js

@@ -0,0 +1,31 @@
+// A Comment Variables config template generated in case no config file has been found. Feel free to use it as a stepping stone to learn how to use Comment Variables.
+
+// As a first step, go ahead and run the command `comment-variables placeholders`.
+// Then rename the `$COMMENT#COMMENT` placeholder next to `alias` to `$COMMENT#ALIAS` and run `comment-variables placeholders` to see what happens.
+// You can now use and explore Comment Variables on the accompanying `comments.example.js` file that has also been generated.
+
+const data = Object.freeze({
+  comment: "This is a comment.",
+  alias: "COMMENT",
+  composed: "$COMMENT#COMMENT $COMMENT#COMMENTS#YES $COMMENT#ALIAS",
+  comments: Object.freeze({
+    yes: "Yes.",
+    no: "No.",
+  }),
+});
+
+const ignores = [];
+
+const lintConfigImports = false; // can be ommitted
+const myIgnoresOnly = false; // can be ommitted
+
+const config = {
+  data,
+  ignores,
+  lintConfigImports,
+  myIgnoresOnly,
+};
+
+export default config;
+
+// Once you've grasped these concepts, simply copy or rename this file to `comments.config.js` and you're good to go.

package/library/_commons/rules/compress.js

@@ -5,9 +5,9 @@ import {
 } from "comment-variables-resolve-config";
 
 /**
- * The utility that creates the compress rule based on the reversed flattened config data, used to transform actual comments into `$COMMENT` placeholders.
- * @param {{[key: string]: string}} reversedFlattenedConfigData The reversed flattened config data, with actual comments as keys and `$COMMENT` placeholders as values.
- * @returns The compress rule based on the reversed flattened config data.
+ * $COMMENT#JSDOC#DEFINITIONS#MAKERULECOMPRESS
+ * @param {{[key: string]: string}} reversedFlattenedConfigData $COMMENT#JSDOC#PARAMS#REVERSEDFLATTENEDCONFIGDATA
+ * @returns $COMMENT#JSDOC#RETURNS#MAKERULECOMPRESS
  */
 const makeRule = (reversedFlattenedConfigData) => {
   /** The whole `reversedFlattenedConfigData` turned from an object to an array of key-value arrays sorted by the descending length of each key to prevent partial replacements. */

package/library/_commons/rules/resolve.js

@@ -4,10 +4,10 @@ import {
 } from "comment-variables-resolve-config";
 
 /**
- * The utility that creates the resolve rule based on the flattened config data, used to transform `$COMMENT` placeholders into actual comments.
- * @param {{[key: string]: string}} flattenedConfigData The flattened config data, with `$COMMENT` placeholders as keys and actual comments as values.
- * @param {{[key: string]: string}} aliases_flattenedKeys The dictionary that connects aliases to their original flattened keys in case an encountered placeholder is actually an alias.
- * @returns The resolve rule based on the flattened config data.
+ * $COMMENT#JSDOC#DEFINITIONS#MAKERULERESOLVE
+ * @param {{[key: string]: string}} flattenedConfigData $COMMENT#JSDOC#PARAMS#FLATTENEDCONFIGDATA
+ * @param {{[key: string]: string}} aliases_flattenedKeys $COMMENT#JSDOC#PARAMS#ALIASES_FLATTENEDKEYS
+ * @returns $COMMENT#JSDOC#RETURNS#MAKERULERESOLVE
  */
 const makeRule = (flattenedConfigData, aliases_flattenedKeys) => {
   /** @type {import('@typescript-eslint/utils').TSESLint.RuleModule<typeof placeholderMessageId, []>} */

package/library/_commons/utilities/flows.js

@@ -21,11 +21,11 @@ import { ruleNames_makeRules } from "../constants/rules.js";
 /* coreCommentsFlow */
 
 /**
- * The core flow at the heart of resolving and compressing comments.
- * @param {typeof resolveRuleName | typeof compressRuleName} ruleName The name of the rule currently used. (Either `"resolve"` or `"compress"`.)
- * @param {string[]} ignores The array of paths and globs for the flow's ESLint instance to ignore.
- * @param {{[key: string]: string}} flattenedConfigData Either the flattened config data or the reversed flattened config data, since they share the same structure.
- * @param {Record<string, string> | undefined} aliases_flattenedKeys The dictionary that connects aliases to their original flattened keys in case an encountered placeholder is actually an alias.
+ * $COMMENT#JSDOC#DEFINITIONS#CORECOMMENTSFLOW
+ * @param {typeof resolveRuleName | typeof compressRuleName} ruleName $COMMENT#JSDOC#PARAMS#RULENAME
+ * @param {string[]} ignores $COMMENT#JSDOC#PARAMS#IGNORES
+ * @param {{[key: string]: string}} flattenedConfigData $COMMENT#JSDOC#PARAMS#EITHERFLATTENEDCONFIGDATA
+ * @param {Record<string, string> | undefined} aliases_flattenedKeys $COMMENT#JSDOC#PARAMS#ALIASES_FLATTENEDKEYS
  * @returns
  */
 const coreCommentsFlow = async (
@@ -104,10 +104,10 @@ const coreCommentsFlow = async (
 /* resolveCommentsFlow */
 
 /**
- * The flow that resolves `$COMMENT` placeholders into actual comments.
- * @param {string[]} ignores The array of paths and globs for the flow's ESLint instance to ignore.
- * @param {Record<string, string>} flattenedConfigData The flattened config data, with `$COMMENT` placeholders as keys and actual comments as values.
- * @param {Record<string, string>} aliases_flattenedKeys The dictionary that connects aliases to their original flattened keys in case an encountered placeholder is actually an alias.
+ * $COMMENT#JSDOC#DEFINITIONS#RESOLVECOMMENTSFLOW
+ * @param {string[]} ignores $COMMENT#JSDOC#PARAMS#IGNORES
+ * @param {Record<string, string>} flattenedConfigData $COMMENT#JSDOC#PARAMS#FLATTENEDCONFIGDATA
+ * @param {Record<string, string>} aliases_flattenedKeys $COMMENT#JSDOC#PARAMS#ALIASES_FLATTENEDKEYS
  * @returns
  */
 export const resolveCommentsFlow = async (
@@ -125,9 +125,9 @@ export const resolveCommentsFlow = async (
 /* compressCommentsFlow */
 
 /**
- * The flow that compresses actual comments into `$COMMENT` placeholders.
- * @param {string[]} ignores The array of paths and globs for the flow's ESLint instance to ignore.
- * @param {{[key: string]: string}} reversedFlattenedConfigData The reversed flattened config data, with actual comments as keys and `$COMMENT` placeholders as values.
+ * $COMMENT#JSDOC#DEFINITIONS#COMPRESSCOMMENTSFLOW
+ * @param {string[]} ignores $COMMENT#JSDOC#PARAMS#IGNORES
+ * @param {{[key: string]: string}} reversedFlattenedConfigData $COMMENT#JSDOC#PARAMS#REVERSEDFLATTENEDCONFIGDATA
  * @returns
  */
 export const compressCommentsFlow = async (
@@ -138,10 +138,10 @@ export const compressCommentsFlow = async (
 /* placeholdersCommentsFlow */
 
 /**
- * The flow that creates `$COMMENT` placeholders right next to where they're defined.
- * @param {string[]} configPathIgnores The array of paths linked to the config file, (named "ignores" given it is ignored by the "compress" and "resolve" commands).
- * @param {{[k: string]: string;}} originalFlattenedConfigData The original flattened config data, before changes to Aliases Variables and Composed Variables are applied.
- * @param {Record<string, string>} aliases_flattenedKeys The dictionary that connects aliases to their original flattened keys in case an encountered placeholder is actually an alias.
+ * $COMMENT#JSDOC#DEFINITIONS#PLACEHOLDERSCOMMENTSFLOW
+ * @param {string[]} configPathIgnores $COMMENT#JSDOC#PARAMS#CONFIGPATHIGNORES
+ * @param {{[k: string]: string;}} originalFlattenedConfigData $COMMENT#JSDOC#PARAMS#ORIGINALFLATTENEDCONFIGDATA
+ * @param {Record<string, string>} aliases_flattenedKeys $COMMENT#JSDOC#PARAMS#ALIASES_FLATTENEDKEYS
  * @returns
  */
 export const placeholdersCommentsFlow = async (

package/library/_commons/utilities/helpers.js

@@ -1,16 +1,16 @@
 /* exitDueToFailure */
 
 /**
- * Terminates the whole process with a 'failure' code (`1`).
- * @returns {never} Never. (Somehow typing needs to be explicit for unreachable code inference.)
+ * $COMMENT#JSDOC#DEFINITIONS#EXITDUETOFAILURE
+ * @returns {never} $COMMENT#JSDOC#RETURNS#EXITDUETOFAILURE
  */
 export const exitDueToFailure = () => process.exit(1);
 
 /* logError */
 
 /**
- * Logs an error to the console depending on its type. (`"error"` or `"warning"`.)
- * @param {{type: "error" | "warning"; message: string}} error The error object being handle for the logging.
+ * $COMMENT#JSDOC#DEFINITIONS#LOGERROR
+ * @param {{type: "error" | "warning"; message: string}} error $COMMENT#JSDOC#PARAMS#ERROR
  * @returns
  */
 export const logError = (error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comment-variables",
-  "version": "0.14.1",
+  "version": "0.14.2",
   "description": "A CLI tool for configuring, managing and maintaining JavaScript comments as JavaScript variables.",
   "bin": {
     "jscomments": "./library/index.js",
@@ -11,8 +11,8 @@
     "library",
     "comments.config.js",
     "comments.config.json",
-    "comments.template.js",
-    "comments.example.js"
+    "generate.template.js",
+    "generate.example.js"
   ],
   "repository": {
     "type": "git",