fix(docs): clean up `npm search` docs

In which the "note on caching" is finally populated after
all these years

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

1 files changed, 54 insertions, 31 deletions

diff --git a/docs/content/commands/npm-search.md b/docs/content/commands/npm-search.md
index 991bfe9e1..33864d472 100644
--- a/docs/content/commands/npm-search.md
+++ b/docs/content/commands/npm-search.md
@@ -16,35 +16,42 @@ aliases: s, se, find
 
 Search the registry for packages matching the search terms. `npm search`
 performs a linear, incremental, lexically-ordered search through package
-metadata for all files in the registry. If color is enabled, it will further
-highlight the matches in the results.
+metadata for all files in the registry. If your terminal has color
+support, it will further highlight the matches in the results.  This can
+be disabled with the config item `color`
 
-Additionally, using the `--searchopts` and `--searchexclude` options paired with
-more search terms will respectively include and exclude further patterns. The
-main difference between `--searchopts` and the standard search terms is that the
-former does not highlight results in the output and can be used for more
-fine-grained filtering. Additionally, both of these can be added to `.npmrc` for
-default search filtering behavior.
+Additionally, using the `--searchopts` and `--searchexclude` options
+paired with more search terms will include and exclude further patterns.
+The main difference between `--searchopts` and the standard search terms
+is that the former does not highlight results in the output and you can
+use them more fine-grained filtering. Additionally, you can add both of
+these to your config to change default search filtering behavior.
 
 Search also allows targeting of maintainers in search results, by prefixing
 their npm username with `=`.
 
-If a term starts with `/`, then it's interpreted as a regular expression and
-supports standard JavaScript RegExp syntax. A trailing `/` will be ignored in
-this case. (Note that many regular expression characters must be escaped or
-quoted in most shells.)
-
-### A Note on caching
+If a term starts with `/`, then it's interpreted as a regular expression
+and supports standard JavaScript RegExp syntax. In this case search will
+ignore a trailing `/` .  (Note you must escape or quote many regular
+expression characters in most shells.)
 
 ### Configuration
 
+All of the following can be defined in a `.npmrc` file, or passed as
+parameters to the cli prefixed with `--` (e.g. `--json`)
+
 #### description
 
 * Default: true
 * Type: Boolean
 
-Used as `--no-description`, disables search matching in package descriptions and
-suppresses display of that field in results.
+#### color
+
+ * Default: true
+ * Type: Boolean
+
+Used as `--no-color`, disables color highlighting of matches in the
+results.
 
 #### json
 
@@ -66,9 +73,9 @@ Output search results as lines with tab-separated columns.
 * Type: Boolean
 
 Display full package descriptions and other long text across multiple
-lines. When disabled (default) search results are truncated to fit
-neatly on a single line. Modules with extremely long names will
-fall on multiple lines.
+lines. When disabled (which is the default) the output will
+truncate search results to fit neatly on a single line. Modules with
+extremely long names will fall on multiple lines.
 
 #### searchopts
 
@@ -84,23 +91,37 @@ Space-separated options that are always passed to search.
 
 Space-separated options that limit the results from search.
 
-#### searchstaleness
-
-* Default: 900 (15 minutes)
-* Type: Number
-
-The age of the cache, in seconds, before another registry request is made.
-
 #### registry
 
  * Default: https://registry.npmjs.org/
  * Type: url
 
-Search the specified registry for modules. If you have configured npm to point
-to a different default registry, such as your internal private module
-repository, `npm search` will default to that registry when searching. Pass a
-different registry url such as the default above in order to override this
-setting.
+Search the specified registry for modules. If you have configured npm to
+point to a different default registry (such as your internal private
+module repository), `npm search` will also default to that registry when
+searching.
+
+### A note on caching
+
+The npm cli caches search results with the same terms and options
+locally in its cache. You can use the following to change how and when
+the cli uses this cache. See [`npm cache`](/commands/npm-cache) for more
+on how the cache works.
+
+#### prefer-online
+
+Forced staleness checks for cached searches, making the cli look for
+updates immediately even for fresh search results.
+
+#### prefer-offline
+
+Bypasses staleness checks for cached.  Missing data will still be
+requested from the server. To force full offline mode, use `offline`.
+
+#### offline
+
+Forces full offline mode. Any searches not locally cached will result in
+an error.
 
 ### See Also
 
@@ -108,3 +129,5 @@ setting.
 * [npm config](/commands/npm-config)
 * [npmrc](/configuring-npm/npmrc)
 * [npm view](/commands/npm-view)
+* [npm cache](/commands/npm-cache)
+* https://npm.im/npm-registry-fetch