feat(help) Add command descriptions to commander output (#5033)

Resolves #1119

**Summary**

#1119 states when typing help for any command, the output is usage and options, but there is no description about what the command actually does.

This pull request makes use of the `setFlags` function and the `commander.description` method to add and print the description of every documented command.

**Test plan**

`yarn run test` run tests for listing cached packages, removing all packages, removing a specific package by name

src/cli/commands/access.js

@@ -4,7 +4,11 @@ import buildSubCommands from './_build-sub-commands.js';
 
 const notYetImplemented = () => Promise.reject(new Error('This command is not implemented yet.'));
 
-export const {run, setFlags, hasWrapper, examples} = buildSubCommands(
+export function setFlags(commander: Object) {
+  commander.description('Has not been implemented yet');
+}
+
+export const {run, hasWrapper, examples} = buildSubCommands(
   'access',
   {
     public: notYetImplemented,

src/cli/commands/add.js

@@ -211,6 +211,7 @@ export function hasWrapper(commander: Object): boolean {
 }
 
 export function setFlags(commander: Object) {
+  commander.description('Installs a package and any packages that it depends on.');
   commander.usage('add [packages ...] [flags]');
   commander.option('-W, --ignore-workspace-root-check', 'required to run yarn add inside a workspace root');
   commander.option('-D, --dev', 'save package to your `devDependencies`');

src/cli/commands/autoclean.js

@@ -152,6 +152,7 @@ export async function run(config: Config, reporter: Reporter, flags: Object, arg
 }
 
 export function setFlags(commander: Object) {
+  commander.description('Cleans and removes unnecessary files from package dependencies.');
   commander.usage('autoclean [flags]');
   commander.option('-I, --init', `Create "${CLEAN_FILENAME}" file with the default entries.`);
   commander.option('-F, --force', `Run autoclean using the existing "${CLEAN_FILENAME}" file.`);

src/cli/commands/bin.js

@@ -10,7 +10,9 @@ export function hasWrapper(commander: Object): boolean {
   return false;
 }
 
-export function setFlags(commander: Object) {}
+export function setFlags(commander: Object) {
+  commander.description('Displays the location of the yarn bin folder.');
+}
 
 export function run(config: Config, reporter: Reporter, flags: Object, args: Array<string>): Promise<void> {
   const binFolder = path.join(config.cwd, config.registries[RegistryYarn.registry].folder, '.bin');

src/cli/commands/cache.js

@@ -125,5 +125,6 @@ export {run, examples};
 
 export function setFlags(commander: Object) {
   _setFlags(commander);
+  commander.description('Yarn cache list will print out every cached package.');
   commander.option('--pattern [pattern]', 'filter cached packages by pattern');
 }

src/cli/commands/check.js

@@ -20,6 +20,7 @@ export function hasWrapper(commander: Object): boolean {
 }
 
 export function setFlags(commander: Object) {
+  commander.description('Verifies if versions in the current project’s package.json match that of yarn’s lock file.');
   commander.option('--integrity');
   commander.option('--verify-tree');
 }

src/cli/commands/config.js

@@ -44,7 +44,11 @@ export function hasWrapper(flags: Object, args: Array<string>): boolean {
   return args[0] !== 'get';
 }
 
-export const {run, setFlags, examples} = buildSubCommands('config', {
+export function setFlags(commander: Object) {
+  commander.description('Manages the yarn configuration files.');
+}
+
+export const {run, examples} = buildSubCommands('config', {
   async set(config: Config, reporter: Reporter, flags: Object, args: Array<string>): Promise<boolean> {
     if (args.length === 0 || args.length > 2) {
       return false;

src/cli/commands/create.js

@@ -8,7 +8,9 @@ import {run as runGlobal, getBinFolder} from './global.js';
 
 const path = require('path');
 
-export function setFlags(commander: Object) {}
+export function setFlags(commander: Object) {
+  commander.description('Creates new projects from any create-* starter kits.');
+}
 
 export function hasWrapper(commander: Object, args: Array<string>): boolean {
   return true;

src/cli/commands/generate-lock-entry.js

@@ -40,6 +40,7 @@ export async function run(config: Config, reporter: Reporter, flags: Object, arg
 }
 
 export function setFlags(commander: Object) {
+  commander.description('Generates a lock file entry.');
   commander.option('--use-manifest <location>', 'description');
   commander.option('--resolved <resolved>', 'description');
   commander.option('--registry <registry>', 'description');

src/cli/commands/global.js

@@ -286,6 +286,7 @@ export {run};
 
 export function setFlags(commander: Object) {
   _setFlags(commander);
+  commander.description('Installs packages globally on your operating system.');
   commander.option('--prefix <prefix>', 'bin prefix to use to install binaries');
   commander.option('--latest', 'upgrade to the latest version of packages');
 }

src/cli/commands/help.js

@@ -12,7 +12,9 @@ export function hasWrapper(flags: Object, args: Array<string>): boolean {
   return false;
 }
 
-export function setFlags(commander: Object) {}
+export function setFlags(commander: Object) {
+  commander.description('Displays help information.');
+}
 
 export function run(config: Config, reporter: Reporter, commander: Object, args: Array<string>): Promise<void> {
   if (args.length) {

src/cli/commands/import.js

@@ -296,7 +296,9 @@ export class Import extends Install {
   }
 }
 
-export function setFlags(commander: Object) {}
+export function setFlags(commander: Object) {
+  commander.description('Generates yarn.lock from an existing npm-installed node_modules folder.');
+}
 
 export function hasWrapper(commander: Object, args: Array<string>): boolean {
   return true;

src/cli/commands/info.js

@@ -36,7 +36,9 @@ function clean(object: any): any {
   }
 }
 
-export function setFlags(commander: Object) {}
+export function setFlags(commander: Object) {
+  commander.description('Shows information about a package.');
+}
 
 export function hasWrapper(commander: Object, args: Array<string>): boolean {
   return true;

src/cli/commands/init.js

@@ -14,6 +14,7 @@ const path = require('path');
 const yn = require('yn');
 
 export function setFlags(commander: Object) {
+  commander.description('Interactively creates or updates a package.json file.');
   commander.option('-y, --yes', 'use default options');
   commander.option('-p, --private', 'use default options and private true');
 }

src/cli/commands/install.js

@@ -924,6 +924,7 @@ export function hasWrapper(commander: Object, args: Array<string>): boolean {
 }
 
 export function setFlags(commander: Object) {
+  commander.description('Yarn install is used to install all dependencies for a project.');
   commander.usage('install [flags]');
   commander.option('-g, --global', 'DEPRECATED');
   commander.option('-S, --save', 'DEPRECATED - save package to your `dependencies`');

src/cli/commands/licenses.js

@@ -91,8 +91,10 @@ async function list(config: Config, reporter: Reporter, flags: Object, args: Arr
     reporter.tree('licenses', trees);
   }
 }
-
-export const {run, setFlags, examples} = buildSubCommands('licenses', {
+export function setFlags(commander: Object) {
+  commander.description('Lists licenses for installed packages.');
+}
+export const {run, examples} = buildSubCommands('licenses', {
   async ls(config: Config, reporter: Reporter, flags: Object, args: Array<string>): Promise<void> {
     reporter.warn(`\`yarn licenses ls\` is deprecated. Please use \`yarn licenses list\`.`);
     await list(config, reporter, flags, args);

src/cli/commands/link.js

@@ -26,7 +26,9 @@ export function hasWrapper(commander: Object, args: Array<string>): boolean {
   return true;
 }
 
-export function setFlags(commander: Object) {}
+export function setFlags(commander: Object) {
+  commander.description('Symlink a package folder during development.');
+}
 
 export async function run(config: Config, reporter: Reporter, flags: Object, args: Array<string>): Promise<void> {
   if (args.length) {

src/cli/commands/list.js

@@ -161,6 +161,7 @@ export function hasWrapper(commander: Object, args: Array<string>): boolean {
 }
 
 export function setFlags(commander: Object) {
+  commander.description('Lists installed packages.');
   commander.option('--depth [depth]', 'Limit the depth of the shown dependencies');
   commander.option('--pattern [pattern]', 'Filter dependencies by pattern');
 }

src/cli/commands/login.js

@@ -110,7 +110,9 @@ export function hasWrapper(commander: Object, args: Array<string>): boolean {
   return true;
 }
 
-export function setFlags(commander: Object) {}
+export function setFlags(commander: Object) {
+  commander.description('Stores registry username and email.');
+}
 
 export async function run(config: Config, reporter: Reporter, flags: Object, args: Array<string>): Promise<void> {
   await getCredentials(config, reporter);

src/cli/commands/logout.js

@@ -3,7 +3,9 @@
 import type {Reporter} from '../../reporters/index.js';
 import type Config from '../../config.js';
 
-export function setFlags(commander: Object) {}
+export function setFlags(commander: Object) {
+  commander.description('Clears registry username and email.');
+}
 
 export function hasWrapper(commander: Object, args: Array<string>): boolean {
   return true;

src/cli/commands/outdated.js

@@ -11,6 +11,7 @@ import colorizeDiff from '../../util/colorize-diff.js';
 export const requireLockfile = true;
 
 export function setFlags(commander: Object) {
+  commander.description('Checks for outdated package dependencies.');
   commander.usage('outdated [packages ...]');
 }
 

src/cli/commands/owner.js

@@ -146,7 +146,11 @@ function remove(config: Config, reporter: Reporter, flags: Object, args: Array<s
   );
 }
 
-export const {run, setFlags, hasWrapper, examples} = buildSubCommands(
+export function setFlags(commander: Object) {
+  commander.description('Manages package owners.');
+}
+
+export const {run, hasWrapper, examples} = buildSubCommands(
   'owner',
   {
     add(config: Config, reporter: Reporter, flags: Object, args: Array<string>): Promise<boolean> {

src/cli/commands/pack.js

@@ -140,6 +140,7 @@ export async function pack(config: Config, dir: string): Promise<stream$Duplex>
 }
 
 export function setFlags(commander: Object) {
+  commander.description('Creates a compressed gzip archive of package dependencies.');
   commander.option('-f, --filename <filename>', 'filename');
 }
 

src/cli/commands/publish.js

@@ -16,6 +16,7 @@ const fs2 = require('fs');
 
 export function setFlags(commander: Object) {
   versionSetFlags(commander);
+  commander.description('Publishes a package to the npm registry.');
   commander.usage('publish [<tarball>|<folder>] [--tag <tag>] [--access <public|restricted>]');
   commander.option('--access [access]', 'access');
   commander.option('--tag [tag]', 'tag');

src/cli/commands/remove.js

@@ -14,7 +14,9 @@ const path = require('path');
 
 export const requireLockfile = true;
 
-export function setFlags(commander: Object) {}
+export function setFlags(commander: Object) {
+  commander.description('Removes a package from your direct dependencies updating your package.json and yarn.lock.');
+}
 
 export function hasWrapper(commander: Object, args: Array<string>): boolean {
   return true;

src/cli/commands/run.js

@@ -12,7 +12,9 @@ const leven = require('leven');
 const path = require('path');
 const {quoteForShell, sh, unquoted} = require('puka');
 
-export function setFlags(commander: Object) {}
+export function setFlags(commander: Object) {
+  commander.description('Runs a defined package script.');
+}
 
 export function hasWrapper(commander: Object, args: Array<string>): boolean {
   return true;

src/cli/commands/tag.js

@@ -84,7 +84,11 @@ async function remove(config: Config, reporter: Reporter, flags: Object, args: A
   }
 }
 
-export const {run, setFlags, hasWrapper, examples} = buildSubCommands(
+export function setFlags(commander: Object) {
+  commander.description('Add, remove, or list tags on a package.');
+}
+
+export const {run, hasWrapper, examples} = buildSubCommands(
   'tag',
   {
     async add(config: Config, reporter: Reporter, flags: Object, args: Array<string>): Promise<boolean> {

src/cli/commands/team.js

@@ -164,7 +164,11 @@ async function list(parts: TeamParts, config: Config, reporter: Reporter): Promi
   return true;
 }
 
-export const {run, setFlags, hasWrapper, examples} = buildSubCommands(
+export function setFlags(commander: Object) {
+  commander.description('Maintain team memberships');
+}
+
+export const {run, hasWrapper, examples} = buildSubCommands(
   'team',
   {
     create: wrapRequiredTeam(async function(

src/cli/commands/unlink.js

@@ -9,7 +9,9 @@ import {getBinFolder as getGlobalBinFolder} from './global';
 
 const path = require('path');
 
-export function setFlags(commander: Object) {}
+export function setFlags(commander: Object) {
+  commander.description('Unlink a previously created symlink for a package.');
+}
 
 export function hasWrapper(commander: Object, args: Array<string>): boolean {
   return true;

src/cli/commands/upgrade-interactive.js

@@ -16,6 +16,7 @@ const path = require('path');
 export const requireLockfile = true;
 
 export function setFlags(commander: Object) {
+  commander.description('Provides an easy way to update outdated packages.');
   commander.usage('upgrade-interactive [flags]');
   commander.option('-S, --scope <scope>', 'upgrade packages under the specified scope');
   commander.option('--latest', 'list the latest version of packages, ignoring version ranges in package.json');

src/cli/commands/upgrade.js

@@ -144,6 +144,7 @@ export function cleanLockfile(
 }
 
 export function setFlags(commander: Object) {
+  commander.description('Upgrades packages to their latest version based on the specified range.');
   commander.usage('upgrade [flags]');
   commander.option('-S, --scope <scope>', 'upgrade packages under the specified scope');
   commander.option('-L, --latest', 'list the latest version of packages, ignoring version ranges in package.json');

src/cli/commands/version.js

@@ -19,6 +19,7 @@ function isValidNewVersion(oldVersion: string, newVersion: string, looseSemver:
 }
 
 export function setFlags(commander: Object) {
+  commander.description('Update the version of your package via the command line.');
   commander.option(NEW_VERSION_FLAG, 'new version');
   commander.option('--message [message]', 'message');
   commander.option('--no-git-tag-version', 'no git tag version');

src/cli/commands/versions.js

@@ -5,7 +5,9 @@ import type Config from '../../config.js';
 
 import {version as yarnVersion} from '../../util/yarn-version.js';
 
-export function setFlags(commander: Object) {}
+export function setFlags(commander: Object) {
+  commander.description('Displays version information of currently installed Yarn, Node.js, and its dependencies.');
+}
 
 export function hasWrapper(commander: Object, args: Array<string>): boolean {
   return true;

src/cli/commands/why.js

@@ -108,7 +108,9 @@ function getSharedDependencies(hoistManifests: HoistManifestTuples, transitiveKe
   return sharedDependencies;
 }
 
-export function setFlags(commander: Object) {}
+export function setFlags(commander: Object) {
+  commander.description('Identifies why a package has been installed, detailing which other packages depend on it.');
+}
 
 export function hasWrapper(commander: Object, args: Array<string>): boolean {
   return true;