Update todos and document a couple functions

Author: hlxid

README.md

@@ -26,8 +26,6 @@ Here's a brief overview of the available commands. More indepth usage guides of
 
 Installs nodecg-io to your current nodecg installation into a sub-directory called `nodecg-io`. Allows you to select which released version you want or if you wish to get a development install.
 
-<!-- TODO: mention that it saves the state and allows for editing by rerunning. Mention updating -->
-
 A production install fetches tarballs of the needed packages from the official npm registry, unpacks them, creates a `package.json` with all packages in a npm v7 workspace configuration and installs dependencies that way.
 
 A development install clones the official git repository (`master`), installs dependencies, bootstraps all packages using lerna and builds all packages.

src/install/index.ts

@@ -10,7 +10,7 @@ import * as os from "os";
 import { logger } from "../log";
 import { requireNpmV7 } from "../npm";
 
-// TODO: remove nodecg-io directory if installation was aborted?
+// TODO: remove nodecg-io directory if initial installation was aborted?
 
 export const installModule: CommandModule<unknown, { concurrency: number }> = {
     command: "install",

src/install/production.ts

@@ -60,6 +60,13 @@ export function diffPackages(
 }
 
 // TODO: handle when e.g. core upgrades and removes nodecg-io-core directory. Need to re-download dashboard because it got deleted (or don't delete it).
+
+/**
+ * Removes a list of packages from a production nodecg-io install.
+ * @param pkgs the packages that should be removed
+ * @param state the current installation info that will be updated with the removals
+ * @param nodecgIODir the nodecg-io directory in which the packages will be removed
+ */
 async function removePackages(pkgs: NpmPackage[], state: ProductionInstallation, nodecgIODir: string): Promise<void> {
     for (const pkg of pkgs) {
         logger.debug(`Removing package ${pkg.name} (${pkg.version})...`);
@@ -70,6 +77,12 @@ async function removePackages(pkgs: NpmPackage[], state: ProductionInstallation,
     logger.info(`Removed ${pkgs.length} packages.`);
 }
 
+/**
+ * Installs a list of packages to a nodecg-io install by fetching, extracting and installing the dependencies.
+ * @param pkgs the packages that should be installed
+ * @param state the current install state that will be updated with the newly added packages
+ * @param nodecgIODir the directory in which nodecg-io is installed an and the new packages should be installed into
+ */
 async function installPackages(pkgs: NpmPackage[], state: ProductionInstallation, nodecgIODir: string): Promise<void> {
     const count = pkgs.length;
     logger.info(`Downloading ${count} packages...`);
@@ -97,6 +110,11 @@ async function installPackages(pkgs: NpmPackage[], state: ProductionInstallation
     await saveProgress(state, nodecgIODir, pkgs, true);
 }
 
+/**
+ * Fetches and extracts a single package from the official npm registry.
+ * @param pkg the package to download
+ * @param nodecgIODir the root directory in which the package with the package path will be fetched into
+ */
 async function fetchSinglePackage(pkg: NpmPackage, nodecgIODir: string): Promise<void> {
     const tarStream = await createNpmPackageReadStream(pkg);
     await extractNpmPackageTar(pkg, tarStream, nodecgIODir);
@@ -114,6 +132,11 @@ async function installNpmDependencies(pkgs: NpmPackage[], nodecgIODir: string):
     await runNpmInstall(nodecgIODir);
 }
 
+/**
+ * Creates a root package.json file with all packages added as a npm v7 workspace.
+ * @param pkgs the packages that are installed and should be included in the npm workspace.
+ * @param nodecgIODir the directory in which nodecg-io is installed
+ */
 async function writeWorkspacePackageJson(pkgs: NpmPackage[], nodecgIODir: string): Promise<void> {
     logger.debug("Creating package.json file for nodecg-io workspace.");
 

src/install/prompt.ts

@@ -129,6 +129,12 @@ function getServicesForVersion(version: string): string[] {
     }
 }
 
+/**
+ * Returns the list of installed services of a production installation.
+ * @param install the installation info for which you want the list of installed services.
+ * @param targetVersion the version of nodecg-io that is installed
+ * @returns the list of installed services (simpleName of the packages without the nodecg-io- prefix)
+ */
 function getServicesFromInstall(install: ProductionInstallation, targetVersion: string): string[] {
     const availableServices = getServicesForVersion(targetVersion);
 

src/installation.ts

@@ -9,6 +9,7 @@ export type Installation = DevelopmentInstallation | ProductionInstallation;
 
 /**
  * A develop version of nodecg-io that is cloned directly form the git repository.
+ * This is the current WIP everything may break version.
  */
 export interface DevelopmentInstallation {
     dev: true;
@@ -19,6 +20,7 @@ export interface DevelopmentInstallation {
 
 /**
  * A production install using released tarballs of the packages from npm.
+ * This is a version from a release.
  */
 export interface ProductionInstallation {
     dev: false;

src/npm.ts

@@ -128,8 +128,6 @@ export async function extractNpmPackageTar(
  * @param path the path where a package.json is present
  */
 export async function runNpmInstall(path: string): Promise<void> {
-    // TODO: npm seems to completely ignore --prod flag when installing inside a workspace.
-    // Is this intentional or is this a bug? Increases install sizes for us because nodecg is huge and a devDependency.
     await executeCommand("npm", ["install", "--prod"], path);
 }