💬 Add Comments

Author: alexlee-dev

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Interactive option. Use the flag `--interactive` to use this mode.
+- Comments :)
 
 ### Changed
 

src/constants.ts

@@ -1,3 +1,6 @@
+/**
+ * These dependencies are required for the cli application regardless of language.
+ */
 export const dependencies = [
   "boxen",
   "chalk",
@@ -7,6 +10,9 @@ export const dependencies = [
   "pickitt",
 ];
 
+/**
+ * These dev dependencies are for JavaScript projects.
+ */
 export const devDependencies = [
   "@babel/core",
   "@babel/cli",
@@ -15,6 +21,9 @@ export const devDependencies = [
   "@babel/runtime",
 ];
 
+/**
+ * These dev dependencies are for TypeScript projects.
+ */
 export const devDependenciesTS = [
   "@types/clear",
   "@types/configstore",

src/index.ts

@@ -3,6 +3,9 @@ import chalk from "chalk";
 import commander from "commander";
 import inquirer from "inquirer";
 
+/**
+ * Initialize Sentry
+ */
 Sentry.init({
   dsn:
     "https://55c913cc3d394f71ba669fda095698fd@o202486.ingest.sentry.io/5254191",
@@ -19,11 +22,20 @@ import {
 } from "./init";
 import { handleIncorrectApplicationName } from "./program";
 
+/**
+ * Main CLI Program
+ */
 const main = async (): Promise<void> => {
   try {
+    // * Used to set the directory, application name, and inserted into templates
     let applicationName;
     let language: "js" | "ts";
+    // * Default language is JavaScript
     language = "js";
+
+    /**
+     * The program that parses the initial user input
+     */
     const program = new commander.Command("create-cli-application")
       .version("0.4.0")
       .arguments("<application-name>")
@@ -55,12 +67,15 @@ const main = async (): Promise<void> => {
       .parse(process.argv);
 
     // TODO - Catch names like "my.app.name" or "my app name"
+
+    // * Application Name must exist, and not consist of illegal characters
     if (applicationName === "." || !applicationName) {
       return handleIncorrectApplicationName(program);
     }
 
     if (program.interactive) {
       // * Interactive walk-thru
+
       // * Language
       const answers = await inquirer.prompt([
         {
@@ -76,23 +91,32 @@ const main = async (): Promise<void> => {
       const languageChoice: "js" | "ts" = answers.language;
       language = languageChoice;
 
+      // TODO - Author Name
       // TODO - Compiler Choice (Babel vs. other)
       // TODO - Add Prettier
       // TODO - Add ESLint / Other Linter
       // TODO - Menu Color Option
     }
+
+    // * Set language to 'ts' if user passed --typescript flag
     if (program.typescript && !program.interactive) language = "ts";
 
+    // * Creates a project directory and package.json
     await createProjectDirectory(applicationName, language);
 
+    // * Installs dependencies
     await installDependencies(applicationName);
 
+    // * Installs dev dependencies
     await installDevDependencies(applicationName, language);
 
+    // * Copies template files and inserts `applicationName` into the files
     await copyTemplateFiles(applicationName, language);
 
+    // * Creates a tsconfig.json file
     if (language === "ts") await createTSConfig(applicationName);
 
+    // * Displays a success message to the user
     displaySuccessMessage(applicationName);
   } catch (error) {
     // TODO - Cleanup

src/init.ts

@@ -7,12 +7,19 @@ import path from "path";
 import { dependencies, devDependencies, devDependenciesTS } from "./constants";
 import { executeCommand } from "./util";
 
+/**
+ * Creates a project directory and a package.json inside that new directory.
+ * @param applicationName Name of application.
+ * @param language Language of application
+ */
 export const createProjectDirectory = async (
   applicationName: string,
   language: "js" | "ts"
 ): Promise<void> => {
+  // * Application Directory
   const root = path.resolve(applicationName);
 
+  // ? Needed?
   fs.ensureDirSync(root);
 
   console.log();
@@ -51,6 +58,7 @@ export const createProjectDirectory = async (
 
   try {
     spinner.start();
+    // * Create package.json
     await fs.writeFile(
       path.join(root, "package.json"),
       JSON.stringify(packageJson, null, 2) + os.EOL
@@ -64,9 +72,14 @@ export const createProjectDirectory = async (
   }
 };
 
+/**
+ * Installs dependencies.
+ * @param applicationName Name of application.
+ */
 export const installDependencies = async (
   applicationName: string
 ): Promise<void> => {
+  // * Application Directory
   const root = path.resolve(applicationName);
 
   let spinner = ora("Installing dependencies");
@@ -76,6 +89,7 @@ export const installDependencies = async (
     const installCommand = "npm";
     let installArgs = ["install", "--save"];
     installArgs = installArgs.concat(dependencies);
+    // * Create a process that installs the dependencies
     await executeCommand(installCommand, installArgs, { cwd: root });
     spinner.succeed("Dependencies installed successfully");
   } catch (error) {
@@ -84,10 +98,16 @@ export const installDependencies = async (
   }
 };
 
+/**
+ * Installs dev dependencies.
+ * @param applicationName Name of application.
+ * @param language Language of application.
+ */
 export const installDevDependencies = async (
   applicationName: string,
   language: "js" | "ts"
 ): Promise<void> => {
+  // * Application Directory
   const root = path.resolve(applicationName);
 
   let spinner = ora("Installing devDependencies");
@@ -104,6 +124,7 @@ export const installDevDependencies = async (
       installArgs = installArgs.concat(devDependencies);
     }
 
+    // * Creates a process that installs the dev dependencies
     await executeCommand(installCommand, installArgs, { cwd: root });
     spinner.succeed("DevDependencies installed successfully");
   } catch (error) {
@@ -112,16 +133,24 @@ export const installDevDependencies = async (
   }
 };
 
+// TODO - Refactor this function :)
+/**
+ * Copies template files and inserts values into the files.
+ * @param applicationName Name of application.
+ * @param language Language of application.
+ */
 export const copyTemplateFiles = async (
   applicationName: string,
   language: "js" | "ts"
 ): Promise<void> => {
+  // * Application Directory
   const root = path.resolve(applicationName);
 
   let spinner = ora("Copying template files");
 
   try {
     spinner.start();
+    // * Copy template files based on language
     await fs.copy(
       path.join(__dirname, `template/${language}/src`),
       path.join(root, "/src")
@@ -252,13 +281,19 @@ export const copyTemplateFiles = async (
   }
 };
 
+/**
+ * Creates a tsconfig.json file in the application directory.
+ * @param applicationName Name of application.
+ */
 export const createTSConfig = async (
   applicationName: string
 ): Promise<void> => {
+  // * Application Directory
   const root = path.resolve(applicationName);
 
   let spinner = ora("Creating tsconfig.json");
 
+  // * Basic tsconfig needed to build the application
   const tsConfig = {
     compilerOptions: {
       target: "es5",
@@ -274,6 +309,7 @@ export const createTSConfig = async (
 
   try {
     spinner.start();
+    // * Create tsconfig.json file
     await fs.writeFile(
       path.join(root, "tsconfig.json"),
       JSON.stringify(tsConfig, null, 2) + os.EOL
@@ -285,7 +321,12 @@ export const createTSConfig = async (
   }
 };
 
+/**
+ * Display a success message to the user.
+ * @param applicationName Name of application.
+ */
 export const displaySuccessMessage = (applicationName: string): void => {
+  // * Application Directory
   const root = path.resolve(applicationName);
 
   console.log();

src/program.ts

@@ -1,6 +1,10 @@
 import chalk from "chalk";
 import commander from "commander";
 
+/**
+ * Handles an incorrectly named application.
+ * @param program Program parsing user input.
+ */
 export const handleIncorrectApplicationName = (program: commander.Command) => {
   console.error("\nPlease specify the name of your application:");
   console.log(
@@ -13,5 +17,6 @@ export const handleIncorrectApplicationName = (program: commander.Command) => {
   console.log(
     `Run ${chalk.cyan(`${program.name()} --help`)} to see all options.`
   );
+  // * Exit the program
   process.exit(1);
 };

src/template/js/src/index.js

@@ -6,16 +6,25 @@ import { titleScreen } from "pickitt";
 import { displayMainMenu, interpretMenuAction } from "./menu";
 import setup from "./setup";
 
+/**
+ * Main Program.
+ */
 const main = async () => {
+  // * Action Emitter keeps track of user input in the menu.
   const menuActionEmitter = new EventEmitter.EventEmitter();
   menuActionEmitter.on("actionCompleted", async (state) => {
+    // * Display title screen
     await titleScreen("___APP NAME___");
+    // * Display main menu
     await displayMainMenu(state);
+    // * When user makes a choice, interpret the choice as an action
     await interpretMenuAction(state);
   });
 
+  // * Store a config file on the user's machine
   const config = new Configstore("___APP NAME___");
 
+  // * Application State
   const state = {
     config,
     menuAction: null,
@@ -26,13 +35,14 @@ const main = async () => {
     const isSetUp = config.get("isSetUp");
 
     if (!isSetUp) {
+      // * The user has not gone through a setup process
+      // * Set up the user
       await setup(state);
       clear();
     }
 
     await titleScreen("___APP NAME___");
     await displayMainMenu(state);
-
     await interpretMenuAction(state);
   } catch (e) {
     console.error("ERROR");
@@ -41,6 +51,7 @@ const main = async () => {
   }
 };
 
+// * Handle local development with `npm start`
 if (process.argv[3] === "start") main();
 
 export default main;

src/template/js/src/setup.js

@@ -2,6 +2,10 @@ import chalk from "chalk";
 import clear from "clear";
 import inquirer from "inquirer";
 
+/**
+ * Walk the user through an initial setup and store values on the machine.
+ * @param {object} state Application State
+ */
 const setup = async (state) => {
   try {
     clear();
@@ -19,9 +23,12 @@ const setup = async (state) => {
         message: `Please enter your ${chalk.yellowBright("special key")}:`,
       },
     ]);
+    // * Template value. Change to be required setup or don't set up at all :)
     const specialKey = answers.specialKey;
     state.config.set("specialKey", specialKey);
 
+    // * Tell the application that the user has gone through this process.
+    // * This value persists thanks to the locally stored configuration.
     state.config.set("isSetUp", true);
   } catch (error) {
     console.error(error);

src/template/ts/src/index.ts

@@ -7,16 +7,25 @@ import { displayMainMenu, interpretMenuAction } from "./menu";
 import setup from "./setup";
 import { AppState } from "./types";
 
+/**
+ * Main Program.
+ */
 const main = async (): Promise<void> => {
+  // * Action Emitter keeps track of user input in the menu.
   const menuActionEmitter = new EventEmitter.EventEmitter();
   menuActionEmitter.on("actionCompleted", async (state: AppState) => {
+    // * Display title screen
     await titleScreen("___APP NAME___");
+    // * Display main menu
     await displayMainMenu(state);
+    // * When user makes a choice, interpret the choice as an action
     await interpretMenuAction(state);
   });
 
+  // * Store a config file on the user's machine
   const config = new Configstore("___APP NAME___");
 
+  // * Application State
   const state: AppState = {
     config,
     menuAction: null,
@@ -27,13 +36,14 @@ const main = async (): Promise<void> => {
     const isSetUp: boolean = config.get("isSetUp");
 
     if (!isSetUp) {
+      // * The user has not gone through a setup process
+      // * Set up the user
       await setup(state);
       clear();
     }
 
     await titleScreen("___APP NAME___");
     await displayMainMenu(state);
-
     await interpretMenuAction(state);
   } catch (e) {
     console.error("ERROR");
@@ -42,6 +52,7 @@ const main = async (): Promise<void> => {
   }
 };
 
+// * Handle local development with `npm start`
 if (process.argv[3] === "start") main();
 
 export default main;