Merge pull request #1079 from spham92/docs

src/choose-blueprint-updates.js

@@ -5,6 +5,13 @@ const inquirer = require('inquirer');
 const loadSafeBlueprint = require('./load-safe-blueprint');
 const { defaultTo } = require('./constants');
 
+/**
+ * Format the string that is displayed when user is prompted for a blueprint
+ *
+ * @param {object} blueprint - Expected to contain `name` and `version` attributes
+ * @param {string} latestVersion - Latest version for the blueprint
+ * @returns {string}
+ */
 function formatBlueprintLine({
   blueprint,
   latestVersion
@@ -26,6 +33,17 @@ async function chooseBlueprint({
   return choicesByName[answer.blueprint];
 }
 
+/**
+ * Facilitate prompting the user for which blueprint they want to update
+ *
+ * @param {string} cwd - Used in `checkForBlueprintUpdates` in order to generate url or path to it if on local disk
+ * @param {object} emberCliUpdateJson - Use the `blueprints` property from this
+ * @param {boolean} reset  - Optional
+ * @param {boolean} compare - Optional
+ * @param {boolean} codemods - Optional
+ * @param {string} to - Optional (could be undefined).
+ * @returns {Promise<{blueprint: (*|{}), areAllUpToDate, to: string}>}
+ */
 async function chooseBlueprintUpdates({
   cwd,
   emberCliUpdateJson,

src/get-base-blueprint.js

@@ -5,6 +5,16 @@ const downloadPackage = require('./download-package');
 const loadSafeBlueprint = require('./load-safe-blueprint');
 const isDefaultBlueprint = require('./is-default-blueprint');
 
+/**
+ * If the passed in `blueprint` is not the base blueprint, find it. A base blueprint is either
+ * an `addon`, `app`, or `glimmer` blueprint or has the `isBaseBlueprint` boolean set to true.
+ *
+ * @param cwd - Used in `parseBlueprintPackage` to read package.json and find a viable version and normalize url
+ * if it exists
+ * @param blueprints - Find the base blueprint in this array if the passed blueprint is not one
+ * @param blueprint - Figure out if this is a base blueprint
+ * @returns {Promise<*>}
+ */
 async function getBaseBlueprint({
   cwd,
   blueprints,

src/get-blueprint-file-path.js

@@ -9,6 +9,13 @@ async function getBlueprintFilePath(cwd) {
   return path.join(cwd, relative);
 }
 
+/**
+ * Use `config` as the parent directory of `ember-cli-update.json` unless a different config
+ * folder is set in the a `package.json` file at the root of the project directory
+ *
+ * @param {String} cwd - Current working directory path where a `package.json` file could exist
+ * @returns {Promise<string>}
+ */
 async function getBlueprintRelativeFilePath(cwd) {
   let configDir = 'config';
 

src/get-project-options.js

@@ -4,6 +4,14 @@ const path = require('path');
 const fs = require('fs-extra');
 const isDefaultBlueprint = require('./is-default-blueprint');
 
+/**
+ * Determine if project is a `addon`, `app`, or `glimmer` type
+ *
+ * @param {function} checkForDep - Function that will check if dependency exists in `devDependencies` or `dependencies`
+ * attribute of `package.json`
+ * @param {array} keywords - Array of strings of the `keywords` attribute from `package.json`
+ * @returns {string}
+ */
 function getProjectType(checkForDep, keywords) {
   let isAddon = keywords && keywords.indexOf('ember-addon') !== -1;
 
@@ -26,6 +34,15 @@ function getProjectType(checkForDep, keywords) {
   throw new Error('Ember CLI project type could not be determined');
 }
 
+/**
+ * Determine what kind of ember flavor this project is and if it uses yarn or npm
+ *
+ * @param {array} keywords - the `keywords` attribute from a `package.json`
+ * @param {object} dependencies - the `dependencies` attribute from a `package.json`
+ * @param {object} devDependencies - the `devDependencies` attribute  from a `package.json`
+ * @param {object} blueprint - Expected to contain `packageName` and `name`
+ * @returns {Promise<[string]|string[]>} - Array of strings containing keywords
+ */
 module.exports = async function getProjectOptions({
   keywords,
   dependencies,

src/get-project-version.js

@@ -5,7 +5,16 @@ const _getProjectVersion = require('boilerplate-update/src/get-project-version')
 
 const glimmerVersionCutoff = '0.6.3';
 
+/**
+ * Fine the minimum version from `versions` array that matches the `packageVersion` range string
+ *
+ * @param {string} packageVersion - Can be a version range such as ^1.0.2 or an exact version
+ * @param {array<string>} versions - Array of version strings available for package
+ * @param {object} projectOptions - Glimmer projects are a special case
+ * @returns {string}
+ */
 module.exports = function getProjectVersion(packageVersion, versions, projectOptions) {
+  // _getProjectVersion gets the minimum version that satisfies the given packageVersion string
   let projectVersion = _getProjectVersion(packageVersion, versions);
 
   if (projectOptions.includes('glimmer') && semver.lt(projectVersion, glimmerVersionCutoff)) {

src/get-versions.js

@@ -2,6 +2,15 @@
 
 const npm = require('boilerplate-update/src/npm');
 
+/**
+ * Returns an array of strings i.e.
+ * [
+ *   "0.0.0",
+ *   "3.23.0-beta.2"
+ * ]
+ * @param packageName
+ * @returns {Promise<Array<string>>}
+ */
 module.exports = async function getVersions(packageName) {
   return await npm.json(`view ${packageName} versions`);
 };

src/index.js

@@ -23,6 +23,17 @@ const resolvePackage = require('./resolve-package');
 const { defaultTo } = require('./constants');
 const normalizeBlueprintArgs = require('./normalize-blueprint-args');
 
+/**
+ * If `version` attribute exists in the `blueprint` object and URL is empty, skip. Otherwise resolve the details of
+ * the blueprint
+ *
+ * @param {Object} blueprint - Expected to contain `name`, `options` array, `packageName`, `location`, and `version`
+ * attributes
+ * @param {String} url - Optional parameter that links to package
+ * @param {String} range - Version range i.e. 1.0.2
+ * @returns {Promise<void>}
+ * @private
+ */
 async function _resolvePackage(blueprint, url, range) {
   if (blueprint.version && !url) {
     return;
@@ -137,6 +148,7 @@ module.exports = async function emberCliUpdate({
     });
   }
 
+  // If blueprint is located on disk
   if (blueprint.location && !packageUrl) {
     let parsedPackage = await parseBlueprintPackage({
       cwd,
@@ -153,6 +165,9 @@ module.exports = async function emberCliUpdate({
     blueprint
   });
 
+  // If no base blueprint is found, set the selected one as the base blueprint.
+  // `glimmer`, `app`, and `addon` blueprints as well as ones whose `isBaseBlueprint` attribute is
+  // set to true will also have baseBlueprint undefined
   if (!baseBlueprint) {
     // for non-existing blueprints
     blueprint.isBaseBlueprint = true;

src/is-default-blueprint.js

@@ -7,6 +7,13 @@ const {
   glimmerPackageName
 } = require('./constants');
 
+/**
+ * A default blueprint either the `addon` or `app` blueprint provided by `ember-cli` or the `glimmer` one
+ *
+ * @param {string} packageName - Ensure this is one of the package names that contain the default blueprints
+ * @param {string} name - Check if this is the name of one of the default blueprint names
+ * @returns {boolean}
+ */
 function isDefaultBlueprint({ packageName, name }) {
   if (packageName === glimmerPackageName && name === glimmerPackageName) {
     return true;

src/load-default-blueprint-from-disk.js

@@ -8,6 +8,14 @@ const getProjectVersion = require('./get-project-version');
 const loadDefaultBlueprint = require('./load-default-blueprint');
 const utils = require('./utils');
 
+/**
+ * Generate the configuration for the "base blueprint" which is the blueprint that first created
+ * the ember project
+ *
+ * @param {string} cwd - Current working directory expected to be a node project path
+ * @param {string} version - Optional. if not pass will use the one specified in package json
+ * @returns {Promise<*|{}>}
+ */
 async function loadDefaultBlueprintFromDisk({
   cwd,
   version
@@ -32,9 +40,7 @@ async function loadDefaultBlueprintFromDisk({
     }
   }
 
-  let blueprint = loadDefaultBlueprint(projectOptions, version);
-
-  return blueprint;
+  return loadDefaultBlueprint(projectOptions, version);
 }
 
 module.exports = loadDefaultBlueprintFromDisk;

src/load-safe-blueprint-file.js

@@ -6,6 +6,22 @@ const semver = require('semver');
 
 const currentSchemaVersion = '1.0.0';
 
+/**
+ * Iterate through the `packages` attribute of the `ember-cli-update.json` file and ensure each
+ * configuration has an `options` attribute
+ *
+ * `emberCliUpdateJson.blueprints` is expected to have at least the following attributes:
+ * {
+ *   packageName: 'package name',
+ *   location: 'Path on disk if local',
+ *   version: '1.2.3',
+ *   options: [],
+ *   ... Any other values
+ * }
+ *
+ * @param {String} emberCliUpdateJsonPath - Path to `ember-cli-update.json` file
+ * @returns {Promise<*>} - Contains object with `blueprints` attribute that is an array
+ */
 async function loadSafeBlueprintFile(emberCliUpdateJsonPath) {
   let emberCliUpdateJson = await loadBlueprintFile(emberCliUpdateJsonPath);
 

src/load-safe-blueprint.js

@@ -1,5 +1,11 @@
 'use strict';
 
+/**
+ * Ensure the blueprint object has a `options` attribute that is an array
+ *
+ * @param {Object} blueprint - Normalize this object into one that has an `options` attribute
+ * @returns Modified `blueprint` object with `options` attribute that is an array
+ */
 function loadSafeBlueprint(blueprint) {
   blueprint = {
     ...blueprint

src/normalize-blueprint-args.js

@@ -1,5 +1,12 @@
 'use strict';
 
+/**
+ * Ensure `packageName` attribute exists. Use the blueprintName if it is missing
+ *
+ * @param {string} packageName - Name of package
+ * @param {string} blueprintName - Name of blueprint
+ * @returns {{blueprintName, packageName}}
+ */
 function normalizeBlueprintArgs({
   packageName,
   blueprintName

src/parse-blueprint-package.js

@@ -14,6 +14,13 @@ function toPosixAbsolutePath(path) {
   return posixPath;
 }
 
+/**
+ * Accommodate situations where `packageName` is a URL or path on local disk.
+ *
+ * @param {string} cwd - Check if path exists concatenated with `packageName` if that is a local path
+ * @param {string} packageName - Can be local path (absolute or relative) or url
+ * @returns {Promise<{name: string, location: string, url: string}>}
+ */
 async function parseBlueprintPackage({
   cwd = '.',
   packageName