fix(docs): autogenerate config docs for commands

Add a script and Makefile rule to build the "Configuration" section for
all command documentation based on the command classes' `params` list.

Also correct several minor problems in the documentation, and add
`params` listings for commands that were lacking them, to match the
existing documentation and/or behavior within the code.

PR-URL: https://github.com/npm/cli/pull/3243
Credit: @isaacs
Close: #3243
Reviewed-by: @wraithgar

45 files changed, 386 insertions, 20 deletions

diff --git a/lib/access.js b/lib/access.js
index 3df611e56..2f0a979ff 100644
--- a/lib/access.js
+++ b/lib/access.js
@@ -28,6 +28,14 @@ class Access extends BaseCommand {
     return 'access'
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return [
+      'registry',
+      'otp',
+    ]
+  }
+
   static get usage () {
     return [
       'public [<package>]',
diff --git a/lib/audit.js b/lib/audit.js
index 9df269858..ea27b0200 100644
--- a/lib/audit.js
+++ b/lib/audit.js
@@ -23,7 +23,7 @@ class Audit extends BaseCommand {
       'force',
       'json',
       'package-lock-only',
-      'production',
+      'omit',
     ]
   }
 
diff --git a/lib/bugs.js b/lib/bugs.js
index 5085a25b4..058971761 100644
--- a/lib/bugs.js
+++ b/lib/bugs.js
@@ -17,6 +17,11 @@ class Bugs extends BaseCommand {
     return ['[<pkgname>]']
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return ['browser', 'registry']
+  }
+
   exec (args, cb) {
     this.bugs(args).then(() => cb()).catch(cb)
   }
diff --git a/lib/cache.js b/lib/cache.js
index 5d544b2db..55fb3e863 100644
--- a/lib/cache.js
+++ b/lib/cache.js
@@ -17,6 +17,11 @@ class Cache extends BaseCommand {
   }
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return ['cache']
+  }
+
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get usage () {
     return [
       'add <tarball file>',
diff --git a/lib/ci.js b/lib/ci.js
index 9ae31950e..d2a27059c 100644
--- a/lib/ci.js
+++ b/lib/ci.js
@@ -30,6 +30,14 @@ class CI extends BaseCommand {
     return 'ci'
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return [
+      'ignore-scripts',
+      'script-shell',
+    ]
+  }
+
   exec (args, cb) {
     this.ci().then(() => cb()).catch(cb)
   }
diff --git a/lib/config.js b/lib/config.js
index 4b3ac5873..d1585f414 100644
--- a/lib/config.js
+++ b/lib/config.js
@@ -50,6 +50,16 @@ class Config extends BaseCommand {
     ]
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return [
+      'json',
+      'global',
+      'editor',
+      'long',
+    ]
+  }
+
   async completion (opts) {
     const argv = opts.conf.argv.remain
     if (argv[1] !== 'config')
diff --git a/lib/dedupe.js b/lib/dedupe.js
index 964902573..e58b6c55f 100644
--- a/lib/dedupe.js
+++ b/lib/dedupe.js
@@ -15,6 +15,22 @@ class Dedupe extends BaseCommand {
     return 'dedupe'
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return [
+      'global-style',
+      'legacy-bundling',
+      'strict-peer-deps',
+      'package-lock',
+      'omit',
+      'ignore-scripts',
+      'audit',
+      'bin-links',
+      'fund',
+      'dry-run',
+    ]
+  }
+
   exec (args, cb) {
     this.dedupe(args).then(() => cb()).catch(cb)
   }
diff --git a/lib/deprecate.js b/lib/deprecate.js
index c640bcfe0..ece55e1f4 100644
--- a/lib/deprecate.js
+++ b/lib/deprecate.js
@@ -21,6 +21,14 @@ class Deprecate extends BaseCommand {
     return ['<pkg>[@<version>] <message>']
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return [
+      'registry',
+      'otp',
+    ]
+  }
+
   async completion (opts) {
     if (opts.conf.argv.remain.length > 1)
       return []
diff --git a/lib/diff.js b/lib/diff.js
index c5e4b403e..1eaceb4f2 100644
--- a/lib/diff.js
+++ b/lib/diff.js
@@ -32,6 +32,22 @@ class Diff extends BaseCommand {
     ]
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return [
+      'diff',
+      'diff-name-only',
+      'diff-unified',
+      'diff-ignore-all-space',
+      'diff-no-prefix',
+      'diff-src-prefix',
+      'diff-dst-prefix',
+      'diff-text',
+      'global',
+      'tag',
+    ]
+  }
+
   get where () {
     const globalTop = resolve(this.npm.globalDir, '..')
     const global = this.npm.config.get('global')
diff --git a/lib/doctor.js b/lib/doctor.js
index 99beb2527..57488fd69 100644
--- a/lib/doctor.js
+++ b/lib/doctor.js
@@ -42,6 +42,11 @@ class Doctor extends BaseCommand {
     return 'doctor'
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return ['registry']
+  }
+
   exec (args, cb) {
     this.doctor(args).then(() => cb()).catch(cb)
   }
diff --git a/lib/edit.js b/lib/edit.js
index 79d41462e..1cf7ca5c2 100644
--- a/lib/edit.js
+++ b/lib/edit.js
@@ -24,6 +24,11 @@ class Edit extends BaseCommand {
   }
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return ['editor']
+  }
+
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
   async completion (opts) {
     return completion(this.npm, opts)
   }
diff --git a/lib/exec.js b/lib/exec.js
index 3da672f99..f30746b8c 100644
--- a/lib/exec.js
+++ b/lib/exec.js
@@ -36,7 +36,7 @@ class Exec extends BaseCommand {
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get params () {
-    return ['workspace', 'workspaces']
+    return ['package', 'call', 'workspace', 'workspaces']
   }
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
diff --git a/lib/explain.js b/lib/explain.js
index 4c2908df6..a34c59a04 100644
--- a/lib/explain.js
+++ b/lib/explain.js
@@ -23,6 +23,11 @@ class Explain extends BaseCommand {
   }
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return ['json']
+  }
+
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
   async completion (opts) {
     return completion(this.npm, opts)
   }
diff --git a/lib/explore.js b/lib/explore.js
index 5f9820c21..4417fba7d 100644
--- a/lib/explore.js
+++ b/lib/explore.js
@@ -23,6 +23,11 @@ class Explore extends BaseCommand {
   }
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return ['shell']
+  }
+
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
   async completion (opts) {
     return completion(this.npm, opts)
   }
diff --git a/lib/find-dupes.js b/lib/find-dupes.js
index 8037876f5..ff2700f5b 100644
--- a/lib/find-dupes.js
+++ b/lib/find-dupes.js
@@ -12,6 +12,21 @@ class FindDupes extends BaseCommand {
     return 'find-dupes'
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return [
+      'global-style',
+      'legacy-bundling',
+      'strict-peer-deps',
+      'package-lock',
+      'omit',
+      'ignore-scripts',
+      'audit',
+      'bin-links',
+      'fund',
+    ]
+  }
+
   exec (args, cb) {
     this.npm.config.set('dry-run', true)
     this.npm.commands.dedupe([], cb)
diff --git a/lib/help-search.js b/lib/help-search.js
index c1ceae441..877989fd0 100644
--- a/lib/help-search.js
+++ b/lib/help-search.js
@@ -21,6 +21,11 @@ class HelpSearch extends BaseCommand {
     return ['<text>']
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return ['long']
+  }
+
   exec (args, cb) {
     this.helpSearch(args).then(() => cb()).catch(cb)
   }
diff --git a/lib/help.js b/lib/help.js
index e9aade521..8e4ff67bc 100644
--- a/lib/help.js
+++ b/lib/help.js
@@ -27,6 +27,11 @@ class Help extends BaseCommand {
     return ['<term> [<terms..>]']
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return ['viewer']
+  }
+
   async completion (opts) {
     if (opts.conf.argv.remain.length > 2)
       return []
diff --git a/lib/hook.js b/lib/hook.js
index 64b1201cb..2ee81bea6 100644
--- a/lib/hook.js
+++ b/lib/hook.js
@@ -13,6 +13,14 @@ class Hook extends BaseCommand {
     return 'hook'
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return [
+      'registry',
+      'otp',
+    ]
+  }
+
   static get usage () {
     return [
       'add <pkg> <url> <secret> [--type=<type>]',
diff --git a/lib/init.js b/lib/init.js
index 7d7f6bab3..bc809a15e 100644
--- a/lib/init.js
+++ b/lib/init.js
@@ -19,7 +19,7 @@ class Init extends BaseCommand {
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get params () {
-    return ['workspace', 'workspaces']
+    return ['yes', 'force', 'workspace', 'workspaces']
   }
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
diff --git a/lib/install-ci-test.js b/lib/install-ci-test.js
index 871f24b2f..0d408178b 100644
--- a/lib/install-ci-test.js
+++ b/lib/install-ci-test.js
@@ -13,6 +13,14 @@ class InstallCITest extends CI {
     return 'install-ci-test'
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return [
+      'ignore-scripts',
+      'script-shell',
+    ]
+  }
+
   exec (args, cb) {
     this.npm.commands.ci(args, (er) => {
       if (er)
diff --git a/lib/install.js b/lib/install.js
index a023015ed..490792a41 100644
--- a/lib/install.js
+++ b/lib/install.js
@@ -26,6 +26,17 @@ class Install extends BaseCommand {
     return [
       'save',
       'save-exact',
+      'global',
+      'global-style',
+      'legacy-bundling',
+      'strict-peer-deps',
+      'package-lock',
+      'omit',
+      'ignore-scripts',
+      'audit',
+      'bin-links',
+      'fund',
+      'dry-run',
     ]
   }
 
diff --git a/lib/link.js b/lib/link.js
index 3e9ec1807..60665a996 100644
--- a/lib/link.js
+++ b/lib/link.js
@@ -30,6 +30,25 @@ class Link extends BaseCommand {
     ]
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return [
+      'save',
+      'save-exact',
+      'global',
+      'global-style',
+      'legacy-bundling',
+      'strict-peer-deps',
+      'package-lock',
+      'omit',
+      'ignore-scripts',
+      'audit',
+      'bin-links',
+      'fund',
+      'dry-run',
+    ]
+  }
+
   async completion (opts) {
     const dir = this.npm.globalDir
     const files = await readdir(dir)
diff --git a/lib/ls.js b/lib/ls.js
index 9fa5fddd5..569156ea2 100644
--- a/lib/ls.js
+++ b/lib/ls.js
@@ -39,6 +39,21 @@ class LS extends BaseCommand {
   }
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return [
+      'all',
+      'json',
+      'long',
+      'parseable',
+      'global',
+      'depth',
+      'omit',
+      'link',
+      'unicode',
+    ]
+  }
+
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
   async completion (opts) {
     return completion(this.npm, opts)
   }
diff --git a/lib/org.js b/lib/org.js
index ddd2b03da..a494e1eaf 100644
--- a/lib/org.js
+++ b/lib/org.js
@@ -22,6 +22,16 @@ class Org extends BaseCommand {
     ]
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return [
+      'registry',
+      'otp',
+      'json',
+      'parseable',
+    ]
+  }
+
   async completion (opts) {
     const argv = opts.conf.argv.remain
     if (argv.length === 2)
diff --git a/lib/outdated.js b/lib/outdated.js
index a436059e9..7516bafe0 100644
--- a/lib/outdated.js
+++ b/lib/outdated.js
@@ -28,6 +28,17 @@ class Outdated extends BaseCommand {
     return ['[[<@scope>/]<pkg> ...]']
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return [
+      'all',
+      'json',
+      'long',
+      'parseable',
+      'global',
+    ]
+  }
+
   exec (args, cb) {
     this.outdated(args).then(() => cb()).catch(cb)
   }
diff --git a/lib/owner.js b/lib/owner.js
index e537d82d0..e57d2268d 100644
--- a/lib/owner.js
+++ b/lib/owner.js
@@ -18,6 +18,14 @@ class Owner extends BaseCommand {
   }
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return [
+      'registry',
+      'otp',
+    ]
+  }
+
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get usage () {
     return [
       'add <user> [<@scope>/]<pkg>',
diff --git a/lib/prefix.js b/lib/prefix.js
index 1298a3c5b..172f8d8fa 100644
--- a/lib/prefix.js
+++ b/lib/prefix.js
@@ -12,6 +12,11 @@ class Prefix extends BaseCommand {
   }
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return ['global']
+  }
+
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get usage () {
     return ['[-g]']
   }
diff --git a/lib/profile.js b/lib/profile.js
index 9789146fd..36e9b03dc 100644
--- a/lib/profile.js
+++ b/lib/profile.js
@@ -57,6 +57,16 @@ class Profile extends BaseCommand {
     ]
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return [
+      'registry',
+      'json',
+      'parseable',
+      'otp',
+    ]
+  }
+
   async completion (opts) {
     var argv = opts.conf.argv.remain
 
diff --git a/lib/prune.js b/lib/prune.js
index 5c4a549d4..4f04c3cdd 100644
--- a/lib/prune.js
+++ b/lib/prune.js
@@ -16,7 +16,7 @@ class Prune extends BaseCommand {
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get params () {
-    return ['production']
+    return ['omit', 'dry-run', 'json']
   }
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
diff --git a/lib/publish.js b/lib/publish.js
index b33839903..ae371b972 100644
--- a/lib/publish.js
+++ b/lib/publish.js
@@ -36,7 +36,7 @@ class Publish extends BaseCommand {
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get params () {
-    return ['tag', 'access', 'dry-run', 'workspace', 'workspaces']
+    return ['tag', 'access', 'dry-run', 'otp', 'workspace', 'workspaces']
   }
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
diff --git a/lib/rebuild.js b/lib/rebuild.js
index 5910ab3d1..9c2d729e7 100644
--- a/lib/rebuild.js
+++ b/lib/rebuild.js
@@ -17,6 +17,15 @@ class Rebuild extends BaseCommand {
   }
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return [
+      'global',
+      'bin-links',
+      'ignore-scripts',
+    ]
+  }
+
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get usage () {
     return ['[[<@scope>/]<name>[@<version>] ...]']
   }
diff --git a/lib/restart.js b/lib/restart.js
index 840eb2067..716ddc909 100644
--- a/lib/restart.js
+++ b/lib/restart.js
@@ -11,5 +11,13 @@ class Restart extends LifecycleCmd {
   static get name () {
     return 'restart'
   }
+
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return [
+      'ignore-scripts',
+      'script-shell',
+    ]
+  }
 }
 module.exports = Restart
diff --git a/lib/run-script.js b/lib/run-script.js
index f781f25c5..ec1042828 100644
--- a/lib/run-script.js
+++ b/lib/run-script.js
@@ -36,7 +36,13 @@ class RunScript extends BaseCommand {
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get params () {
-    return ['workspace', 'workspaces']
+    return [
+      'workspace',
+      'workspaces',
+      'if-present',
+      'ignore-scripts',
+      'script-shell',
+    ]
   }
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
diff --git a/lib/search.js b/lib/search.js
index bdd374ab6..e67f9cc91 100644
--- a/lib/search.js
+++ b/lib/search.js
@@ -41,8 +41,15 @@ class Search extends BaseCommand {
     return [
       'long',
       'json',
+      'color',
       'parseable',
       'description',
+      'searchopts',
+      'searchexclude',
+      'registry',
+      'prefer-online',
+      'prefer-offline',
+      'offline',
     ]
   }
 
diff --git a/lib/star.js b/lib/star.js
index 4c5cf4900..bed9c5c43 100644
--- a/lib/star.js
+++ b/lib/star.js
@@ -20,6 +20,14 @@ class Star extends BaseCommand {
     return ['[<pkg>...]']
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return [
+      'registry',
+      'unicode',
+    ]
+  }
+
   exec (args, cb) {
     this.star(args).then(() => cb()).catch(cb)
   }
diff --git a/lib/stars.js b/lib/stars.js
index db93d7b19..f44344515 100644
--- a/lib/stars.js
+++ b/lib/stars.js
@@ -20,6 +20,13 @@ class Stars extends BaseCommand {
     return ['[<user>]']
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return [
+      'registry',
+    ]
+  }
+
   exec (args, cb) {
     this.stars(args).then(() => cb()).catch(er => {
       if (er.code === 'ENEEDAUTH')
diff --git a/lib/start.js b/lib/start.js
index 099b6e61b..0251bff67 100644
--- a/lib/start.js
+++ b/lib/start.js
@@ -11,5 +11,13 @@ class Start extends LifecycleCmd {
   static get name () {
     return 'start'
   }
+
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return [
+      'ignore-scripts',
+      'script-shell',
+    ]
+  }
 }
 module.exports = Start
diff --git a/lib/stop.js b/lib/stop.js
index 766d9c018..ec5fe76ad 100644
--- a/lib/stop.js
+++ b/lib/stop.js
@@ -11,5 +11,13 @@ class Stop extends LifecycleCmd {
   static get name () {
     return 'stop'
   }
+
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return [
+      'ignore-scripts',
+      'script-shell',
+    ]
+  }
 }
 module.exports = Stop
diff --git a/lib/team.js b/lib/team.js
index 5298bb3b2..46d5a0977 100644
--- a/lib/team.js
+++ b/lib/team.js
@@ -25,6 +25,16 @@ class Team extends BaseCommand {
     ]
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return [
+      'registry',
+      'otp',
+      'parseable',
+      'json',
+    ]
+  }
+
   async completion (opts) {
     const { conf: { argv: { remain: argv } } } = opts
     const subcommands = ['create', 'destroy', 'add', 'rm', 'ls']
diff --git a/lib/test.js b/lib/test.js
index 2be2b54af..e78fdf0c7 100644
--- a/lib/test.js
+++ b/lib/test.js
@@ -12,6 +12,14 @@ class Test extends LifecycleCmd {
     return 'test'
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return [
+      'ignore-scripts',
+      'script-shell',
+    ]
+  }
+
   exec (args, cb) {
     super.exec(args, er => {
       if (er && er.code === 'ELIFECYCLE') {
diff --git a/lib/token.js b/lib/token.js
index a80988531..64015d7d4 100644
--- a/lib/token.js
+++ b/lib/token.js
@@ -28,6 +28,16 @@ class Token extends BaseCommand {
     ]
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return [
+      'read-only',
+      'cidr',
+      'registry',
+      'otp',
+    ]
+  }
+
   async completion (opts) {
     const argv = opts.conf.argv.remain
     const subcommands = ['list', 'revoke', 'create']
diff --git a/lib/unpublish.js b/lib/unpublish.js
index d49bb7ba4..8030bb403 100644
--- a/lib/unpublish.js
+++ b/lib/unpublish.js
@@ -26,6 +26,11 @@ class Unpublish extends BaseCommand {
     return ['[<@scope>/]<pkg>[@<version>]']
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return ['force']
+  }
+
   async completion (args) {
     const { partialWord, conf } = args
 
diff --git a/lib/unstar.js b/lib/unstar.js
index bc32ba617..36ce1daf1 100644
--- a/lib/unstar.js
+++ b/lib/unstar.js
@@ -11,6 +11,15 @@ class Unstar extends Star {
     return 'unstar'
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return [
+      'registry',
+      'unicode',
+      'otp',
+    ]
+  }
+
   exec (args, cb) {
     this.npm.config.set('star.unstar', true)
     super.exec(args, cb)
diff --git a/lib/update.js b/lib/update.js
index f8cb12d26..ff9ef9d5e 100644
--- a/lib/update.js
+++ b/lib/update.js
@@ -20,7 +20,19 @@ class Update extends BaseCommand {
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get params () {
-    return ['global']
+    return [
+      'global',
+      'global-style',
+      'legacy-bundling',
+      'strict-peer-deps',
+      'package-lock',
+      'omit',
+      'ignore-scripts',
+      'audit',
+      'bin-links',
+      'fund',
+      'dry-run',
+    ]
   }
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
diff --git a/lib/utils/config/definitions.js b/lib/utils/config/definitions.js
index aa90de8e7..22fff3878 100644
--- a/lib/utils/config/definitions.js
+++ b/lib/utils/config/definitions.js
@@ -710,6 +710,7 @@ define('force', {
       dependency range (including SemVer-major changes).
     * Allow unpublishing all versions of a published package.
     * Allow conflicting peerDependencies to be installed in the root project.
+    * Implicitly set \`--yes\` during \`npm init\`.
 
     If you don't have a clear idea of what you want to do, it is strongly
     recommended that you do not use this option!
@@ -859,6 +860,11 @@ define('ignore-scripts', {
   type: Boolean,
   description: `
     If true, npm does not run scripts specified in package.json files.
+
+    Note that commands explicitly intended to run a particular script, such
+    as \`npm start\`, \`npm stop\`, \`npm restart\`, \`npm test\`, and \`npm
+    run-script\` will still run their intended script if \`ignore-scripts\` is
+    set, but they will *not* run any pre- or post-scripts.
   `,
   flatten,
 })
@@ -1019,10 +1025,7 @@ define('json', {
   description: `
     Whether or not to output JSON data, rather than the normal output.
 
-    This feature is currently experimental, and the output data structures
-    for many commands is either not implemented in JSON yet, or subject to
-    change.  Only the output from \`npm ls --json\` and \`npm search --json\`
-    are currently valid.
+    Not supported by all npm commands.
   `,
   flatten,
 })
@@ -1090,6 +1093,8 @@ define('link', {
     * The package is not already installed globally, or
     * the globally installed version is identical to the version that is
       being installed locally.
+
+    When used with \`npm ls\`, only show packages that are linked.
   `,
 })
 
@@ -1139,7 +1144,7 @@ define('long', {
   type: Boolean,
   short: 'l',
   description: `
-    Show extended information in \`npm ls\` and \`npm search\`.
+    Show extended information in \`ls\`, \`search\`, and \`help-search\`.
   `,
 })
 
@@ -1226,7 +1231,7 @@ define('offline', {
 define('omit', {
   default: process.env.NODE_ENV === 'production' ? ['dev'] : [],
   defaultDescription: `
-    'dev' if the NODE_ENV environment variable is set to 'production',
+    'dev' if the \`NODE_ENV\` environment variable is set to 'production',
     otherwise empty.
   `,
   type: [Array, 'dev', 'optional', 'peer'],
@@ -1627,15 +1632,27 @@ define('scope', {
   description: `
     Associate an operation with a scope for a scoped registry.
 
-    Useful when logging in to a private registry for the first time:
+    Useful when logging in to or out of a private registry:
 
-    \`\`\`bash
+    \`\`\`
+    # log in, linking the scope to the custom registry
     npm login --scope=@mycorp --registry=https://registry.mycorp.com
+
+    # log out, removing the link and the auth token
+    npm logout --scope=@mycorp
     \`\`\`
 
     This will cause \`@mycorp\` to be mapped to the registry for future
     installation of packages specified according to the pattern
     \`@mycorp/package\`.
+
+    This will also cause \`npm init\` to create a scoped package.
+
+    \`\`\`
+    # accept all defaults, and create a package named "@foo/whatever",
+    # instead of just named "whatever"
+    npm init --scope=@foo --yes
+    \`\`\`
   `,
   flatten (key, obj, flatOptions) {
     const value = obj[key]
@@ -1832,6 +1849,9 @@ define('tag', {
 
     Also the tag that is added to the package@version specified by the \`npm
     tag\` command, if no explicit tag is given.
+
+    When used by the \`npm diff\` command, this is the tag used to fetch the
+    tarball that will be compared with the local files by default.
   `,
   flatten (key, obj, flatOptions) {
     flatOptions.defaultTag = obj[key]
@@ -1911,7 +1931,7 @@ define('unicode', {
   default: unicode,
   defaultDescription: `
     false on windows, true on mac/unix systems with a unicode locale, as
-    defined by the LC_ALL, LC_CTYPE, or LANG environment variables.
+    defined by the \`LC_ALL\`, \`LC_CTYPE\`, or \`LANG\` environment variables.
   `,
   type: Boolean,
   description: `
@@ -2050,10 +2070,15 @@ define('workspace', {
     this configuration option.
 
     Valid values for the \`workspace\` config are either:
-    - Workspace names
-    - Path to a workspace directory
-    - Path to a parent workspace directory (will result to selecting all of the
-    nested workspaces)
+
+    * Workspace names
+    * Path to a workspace directory
+    * Path to a parent workspace directory (will result to selecting all of the
+      nested workspaces)
+
+    When set for the \`npm init\` command, this may be set to the folder of
+    a workspace which does not yet exist, to create the folder and set it
+    up as a brand new workspace within the project.
   `,
 })