features: make cli help interface more documented

packages/webpack-cli/lib/groups/HelpGroup.js

@@ -21,10 +21,10 @@ class HelpGroup {
             const link = options.link;
 
             process.stdout.write(`${header('Usage')}: ${usage}\n`);
-            process.stdout.write(`${header('Description')}: ${description}\n`);
+            process.stdout.write(`\n${header('Description')}: ${description}\n`);
 
             if (link) {
-                process.stdout.write(`${header('Documentation')}: ${link}\n`);
+                process.stdout.write(`\n${header('Documentation')}: ${link}\n`);
             }
 
             if (options.flags) {
@@ -96,12 +96,16 @@ class HelpGroup {
             {
                 header: 'Available Commands',
                 content: options.commands.map((e) => {
-                    return { name: e.name, summary: e.description };
+                    return { name: e.name, summary: e.shortDesc ? e.shortDesc : e.description };
                 }),
             },
             {
                 header: 'Options',
-                optionList: options.core,
+                optionList: options.core.map((e) => {
+                    const description = e.shortDesc ? e.shortDesc : e.description;
+                    e.description = description;
+                    return e;
+                }),
             },
         ]);
         return {

packages/webpack-cli/lib/utils/cli-flags.js

@@ -9,6 +9,13 @@ const ADVANCED_GROUP = 'advanced';
 const DISPLAY_GROUP = 'stats';
 const ZERO_CONFIG_GROUP = 'zero-config';
 
+function acceptedString(arr) {
+    return `Accepted Value: ${arr.join(' | ')}`;
+}
+function descriptionGenerator(example, shortDesc, acceptedValue = []) {
+    return `\n\n    Example: ${example}\n\n     ${acceptedValue.length > 0 ? acceptedString(acceptedValue) : ''}\n\n${shortDesc}`;
+}
+
 module.exports = {
     groups: {
         HELP_GROUP,
@@ -79,7 +86,11 @@ module.exports = {
             type: String,
             defaultOption: true,
             group: BASIC_GROUP,
-            description: 'The entry point of your application.',
+            shortDesc: 'The entry point of your application.',
+            description: descriptionGenerator(
+                'webpack --entry index.js',
+                'It is the entry point of your application. You can provide multiple entry points also.',
+            ),
             link: 'https://webpack.js.org/concepts/#entry',
         },
         {
@@ -89,7 +100,11 @@ module.exports = {
             type: String,
             defaultValue: null,
             group: CONFIG_GROUP,
-            description: 'Provide path to a webpack configuration file',
+            shortDesc: 'Provide path to a webpack configuration file',
+            description: descriptionGenerator(
+                'webpack-cli --config ./webpack.config.js',
+                'It provides path to a webpack configuration file',
+            ),
             link: 'https://webpack.js.org/configuration/',
         },
         {
@@ -136,15 +151,17 @@ module.exports = {
             alias: 'o',
             group: OUTPUT_GROUP,
             type: String,
-            description: 'Output location of the file generated by webpack',
+            shortDesc: 'Output location of the file generated by webpack',
+            description: descriptionGenerator('webpack --output ./a.js', 'Output location to the file generated by webpack'),
             link: 'https://webpack.js.org/concepts/#output',
         },
         {
             name: 'plugin',
-            usage: '--plugin',
+            usage: '--plugin <plugin name> e.g. HtmlWebpackPlugin',
             group: ADVANCED_GROUP,
             type: String,
-            description: 'Load a given plugin',
+            shortDesc: 'Load a given plugin',
+            description: descriptionGenerator('webpack --plugin ExtractTextWebpackPlugin', 'Load a plugin '),
             link: 'https://webpack.js.org/plugins/',
         },
         {
@@ -162,7 +179,17 @@ module.exports = {
             alias: 't',
             type: String,
             group: ADVANCED_GROUP,
-            description: 'Sets the build target',
+            shortDesc: 'Sets the build target',
+            description: descriptionGenerator('webpack --target node ', 'Instructs webpack to target a specific environment.', [
+                'async-node',
+                'electron-main',
+                'electron-renderer',
+                'electron-preload',
+                'node',
+                'node-webkit',
+                'web',
+                'webworker',
+            ]),
             link: 'https://webpack.js.org/configuration/target/#target',
         },
         {
@@ -279,7 +306,12 @@ module.exports = {
                 return 'normal';
             },
             group: DISPLAY_GROUP,
-            description: 'It instructs webpack on how to treat the stats',
+            shortDesc: 'It instructs webpack on how to treat the stats',
+            description: descriptionGenerator(
+                'npx webpack-cli --stats verbose',
+                'These options instructs webpack on how to treat the stats.',
+                StatsGroup.validOptions(),
+            ),
             link: 'https://webpack.js.org/configuration/stats/#stats',
         },
         {

test/help/help-multi-args.test.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const { run } = require('../utils/test-utils');
-const outputDescription = 'Output location of the file generated by webpack';
+const outputDescription = 'Output location to the file generated by webpack';
 const createDescription = 'Initialize a new webpack configuration';
 describe('help flag with multiple arguments', () => {
     it('outputs info with dashed syntax', () => {

test/help/help-single-arg.test.js

@@ -5,8 +5,8 @@ const { run } = require('../utils/test-utils');
 const helpHeader = 'The build tool for modern web applications';
 
 describe('single help flag', () => {
-    it('respects --color flag as false', () => {
-        const { stdout, stderr } = run(__dirname, ['--help', '--color=false'], false);
+    it('check default color enabled', () => {
+        const { stdout, stderr } = run(__dirname, ['--help'], false);
         const usage = 'webpack [...options] | <command>';
         const example = 'webpack help --flag | <command>';
         chalk.enabled = true;

test/info/info-help.test.js

@@ -29,8 +29,8 @@ describe('should print help for info command', () => {
         expect(stderr).toHaveLength(0);
     });
 
-    it('should respect the --color=false flag', () => {
-        const { stdout, stderr } = runInfo(['info', 'help', '--color=false']);
+    it('should be default colored as commands', () => {
+        const { stdout, stderr } = runInfo(['info', 'help']);
         chalk.enabled = true;
         chalk.level = 3;
         const orange = chalk.keyword('orange');