Deep editing pass on documentation (#2531)

Author: dgr

doc/clojurescript.md

@@ -1,30 +1,34 @@
 ## ClojureScript
 
-CIDER works with ClojureScript, but you should keep in mind that not all
-the functionality available with Clojure exists for ClojureScript (at least
-not yet). To give you a concrete example - things like running tests and
-the debugger are currently Clojure-only features.
+CIDER works well with ClojureScript, but not all CIDER features are
+available in ClojureScript (yet). For instance, the test runner and
+debugger are currently Clojure-only features. Unlike the Clojure
+ecosystem that is dominated by Leiningen and Boot, the ClojureScript
+ecosystem has a number of different choices for REPLs. You'll have to
+decide which one you want to run and how you want CIDER to interact
+with it. This chapter describes some of the more common choices
+and the configurations required to get them working.
 
 
 ### Piggieback
 
 ClojureScript support relies on the [piggieback][] nREPL middleware
 being present in your REPL session. There's one exception to this,
-though - [shadow-cljs][]. It has its own nREPL middleware and doesn't rely
+though: [shadow-cljs][]. It has its own nREPL middleware and doesn't rely
 on piggieback at all.
 
-If `cider-inject-dependencies-at-jack-in` is enabled (which is the default) then
-piggieback will be automatically added and configured for your project when
-doing `cider-jack-in-cljs`.
+If `cider-inject-dependencies-at-jack-in` is enabled, which it is by
+default, then piggieback will be automatically added and configured
+for your project when doing `cider-jack-in-cljs`.
 
-If this configuration option is disabled or you're going to connect to
-an already running nREPL server using `cider-connect-cljs` - continue
-reading ahead.
+If `cider-inject-dependencies-at-jack-in` is disabled or you're going
+to connect to an already running nREPL server using
+`cider-connect-cljs`, use the configuration in the following section.
 
 #### Manual Piggieback Setup
 
-To setup piggieback add the following dependencies to your project
-(`project.clj` in Leiningen based project or `build.boot` in Boot
+To setup piggieback, add the following dependencies to your project
+(`project.clj` in a Leiningen based project or `build.boot` in a Boot
 project):
 
 ```clojure
@@ -50,32 +54,37 @@ or in `build.boot`:
 
 ### Starting a ClojureScript REPL
 
-There are many ClojureScript REPLs out there and it's often hard to wrap your
-head around them and the differences between them. You'd do well to read [this
-awesome article](https://lambdaisland.com/guides/clojure-repls/clojurescript-repls)
-before proceeding with the rest of the instructions listed here.
+!!! Tip
 
-Open a file in your project and issue <kbd>M-x</kbd>
+    There are many ClojureScript REPLs available, each offering a
+    different set of capabilities and features. As background for this
+    section, you might want to read [this awesome
+    article](https://lambdaisland.com/guides/clojure-repls/clojurescript-repls)
+    before proceeding.
+
+Open a file in your project and type <kbd>M-x</kbd>
 `cider-jack-in-cljs` <kbd>RET</kbd>. This will start up the nREPL
-server, and then create a ClojureScript REPL buffer for you, one.
+server and create a ClojureScript REPL buffer.
 
 !!! Note
 
     Prior to CIDER 0.18, `cider-jack-in-cljs` would create both a Clojure and
     a ClojureScript REPL. In CIDER 0.18+ if you want to create both REPLs
     you'll have to use `cider-jack-in-clj&cljs` instead.
 
-When you have a combination of Clojure and ClojureScript REPLs all
-usual CIDER commands will be automatically directed to the appropriate
-REPL, depending on whether you're visiting a `.clj` or a `.cljs` file.
+When you have a combination of Clojure and ClojureScript REPLs, CIDER
+will automatically direct all the usual CIDER commands to the
+appropriate REPL based on whether you're currently visitng a `.clj` or
+`.cljs` file.
 
-`cider-jack-in-cljs` will prompt you about the type of
-ClojureScript to start. Keep in mind that some of the REPLs will
-require some additional setup, before you can make use of them (e.g. you'll
-need to have Node.js installed to be able to start a node REPL).
+`cider-jack-in-cljs` will prompt you for the type of ClojureScript
+REPL you want to start. Keep in mind that some of the REPLs will
+require you to configure additional setup. For example, you'll need to
+have Node.js installed to be able to start a Node REPL.
 
-You can suppress the prompt the REPL to use by setting `cider-default-cljs-repl`.
-Here's an example that will make Nashorn the default:
+If you frequently use the same ClojureScript REPL, you can set
+`cider-default-cljs-repl` and CIDER will skip the prompt and use this
+instead. For example, the following will make Nashorn the default:
 
 ```el
 (setq cider-default-cljs-repl 'nashorn)
@@ -106,20 +115,20 @@ You can also modify the known ClojureScript REPLs on a per-project basis using
   (cider-default-cljs-repl . super-cljs)))
 ```
 
-You can also create a ClojureScript REPL with the command
-`cider-jack-in-sibling-clojurescript` in cases where you already have a
-Clojure REPL running.
+If you already have a Clojure REPL running and want to add a
+ClojureScript REPL, you can invoke
+`cider-jack-in-sibling-clojurescript` to add it.
 
-Continue reading for the additional setup needed for the various ClojureScript
-REPLs out there.
+The following sections describe the configurations for several common
+CloudScript REPL use cases.
 
-### Browser-connected ClojureScript REPL
+### Browser-Connected ClojureScript REPL
 
 Using Weasel, you can also have a browser-connected REPL.
 
 1. Add `[weasel "0.7.0"]` to your project's `:dependencies`.
 
-2. Issue <kbd>M-x</kbd> `cider-jack-in-cljs` <kbd>RET</kbd> and choose
+2. Type <kbd>M-x</kbd> `cider-jack-in-cljs` <kbd>RET</kbd> and choose
    the `Weasel` option when prompted about the ClojureScript REPL type you want
    to use.
 
@@ -131,15 +140,15 @@ Using Weasel, you can also have a browser-connected REPL.
 (repl/connect "ws://localhost:9001")
 ```
 
-4. Open a file in your project and issue <kbd>M-x</kbd> `cider-jack-in-cljs`.
+4. Open a file in your project and type <kbd>M-x</kbd> `cider-jack-in-cljs`.
 
 Provided that a Piggieback-enabled ClojureScript environment is active in your
 REPL session, code loading and evaluation will work seamlessly regardless of the
 presence of the `cider-nrepl` middleware. If the middleware is present then most
 other features of CIDER will also be enabled (including code completion,
 documentation lookup, the namespace browser, and macroexpansion).
 
-### Browser-connected ClojureScript REPL in Boot project
+### Browser-Connected ClojureScript REPL in Boot Projects
 
 1. Add this to your dependencies in `build.boot`:
 
@@ -166,10 +175,10 @@ and this at the end of `build.boot`:
         (cljs)))
 ```
 
-2. Issue <kbd>M-x</kbd> `customize-variable` <kbd>RET</kbd> `cider-boot-parameters`
+2. Type <kbd>M-x</kbd> `customize-variable` <kbd>RET</kbd> `cider-boot-parameters`
    and insert `dev`.
 
-3. Open a file in your project and issue <kbd>M-x</kbd> `cider-jack-in-cljs`.
+3. Open a file in your project and type <kbd>M-x</kbd> `cider-jack-in-cljs`.
 
 5. Connect to the running server with your browser. The address is printed on the terminal, but it's probably `http://localhost:3000`.
 
@@ -195,7 +204,7 @@ You can also use [Figwheel](https://github.com/bhauman/lein-figwheel) with CIDER
 ```
 
 Keep in mind that figwheel 0.5.16 is the first to support piggieback
-0.3. If you're using an older figwheel you should stick to piggieback
+0.3. If you're using an older figwheel, you should stick to piggieback
 0.2.2 (which uses the old `com.cemerick/piggieback` package coordinates).
 
 3. Add this to your dev `:repl-options` (not needed for `cider-jack-in-cljs`):
@@ -205,7 +214,7 @@ Keep in mind that figwheel 0.5.16 is the first to support piggieback
 ```
 
 4. Start the REPL with `cider-jack-in-cljs` (<kbd>C-c C-x (C-)j (C-)s</kbd>). Select
-`figwheel` when prompted about the ClojureScript REPL type.
+`figwheel` when prompted for the ClojureScript REPL type.
 
 5. Open a browser to the Figwheel URL so that it can connect to your application.
 
@@ -221,10 +230,10 @@ You should also check out
 
 You can also use [Figwheel-main](https://github.com/bhauman/figwheel-main) with CIDER.
 
-1. Add this to your dev `:dependencies`:
+1. Add this to your dev `:dependencies` (not needed for `cider-jack-in-cljs`):
 
 ```clojure
-[cider/piggieback "0.3.10"] ; not needed for cider-jack-in-cljs
+[cider/piggieback "0.3.10"]
 ```
 
 2. Add this to your dev `:repl-options` (not needed for `cider-jack-in-cljs`):
@@ -233,30 +242,31 @@ You can also use [Figwheel-main](https://github.com/bhauman/figwheel-main) with
 :nrepl-middleware [cider.piggieback/wrap-cljs-repl]
 ```
 
-3. Start the REPL with `cider-jack-in-cljs` (<kbd>C-c C-x (C-)j (C-)s</kbd>). Select
-`figwheel-main` when prompted about the ClojureScript REPL type.
+3. Start the REPL with `cider-jack-in-cljs` (<kbd>C-c C-x (C-)j
+(C-)s</kbd>). When CIDER prompts about the ClojureScript REPL type,
+type `figwheel-main`.
 
 4. Select the Figwheel build to run when prompted for it. (e.g. `:dev`).
 
 ### Using shadow-cljs
 
-Provided you've configured your project correctly you can simply use
-`cider-jack-in-cljs` to use `shadow-cljs`.
+Provided you've configured your project correctly, you can simply use
+`cider-jack-in-cljs` for `shadow-cljs`.
 
-This will automatically start the shadow-cljs server and connect to it. You'll also
-be prompted for the build to use.
+This will automatically start the shadow-cljs server and connect to
+it. You'll also be prompted for the build to use.
 
 Alternatively you can start the server manually with something like:
 
-```
-npx shadow-cljs server
+```sh
+$ npx shadow-cljs server
 ```
 
 And connect to it with `cider-connect`.
 
-Lastly, if you already have a running server watching a build, for instance you
-have already run `npx shadow-cljs watch :dev`, you can use the `shadow-select`
-CLJS REPL and specify `:dev` when prompted.
+If you already have a running server watching a build (for instance
+you have already run `npx shadow-cljs watch :dev`), you can use the
+`shadow-select` CLJS REPL and specify `:dev` when prompted.
 
 [leiningen]: http://leiningen.org/
 [boot]: http://boot-clj.com/
@@ -265,14 +275,16 @@ CLJS REPL and specify `:dev` when prompted.
 
 ## Working with `.cljc` files
 
-Ordinarily, CIDER dispatches code from `clj` files to Clojure REPLs and `cljs`
-files to ClojureScript REPLs. However, `cljc` files have two possible connection
-targets. By default, CIDER tries to evaluate `cljc` files in all matching
-connection buffers, both `clj` and `cljs` (if present).
-
-Simply put - if you're evaluating the code `(+ 2 2)` in a `cljc` file and you
-have an active Clojure and and active ClojureScript REPL, then the code is going
-to be evaluated twice - once for each of the REPLs.  In fact, you can create
-multiple clj and cljs sibling connections (<kbd>C-c C-x C-s C-s/j</kbd>) within
-Cider session and evaluation will be directed into all REPLs simultaneously. See
-[Managing Connections](managing_connections.md) for more details.
+Ordinarily, CIDER dispatches code from `clj` files to Clojure REPLs
+and `cljs` files to ClojureScript REPLs. But`cljc` files have two
+possible connection targets, both of which are valid. So, by default,
+CIDER tries to evaluate `cljc` files in all matching connection
+buffers, both `clj` and `cljs`, if present.
+
+Thus, if you're evaluating the code `(+ 2 2)` in a `cljc` file and you
+have both an active Clojure and ClojureScript REPL then the code is
+going to be evaluated twice, once in each of the REPLs.  In fact, you
+can create multiple clj and cljs sibling connections (<kbd>C-c C-x C-s
+C-s/j</kbd>) within a CIDER session and evaluation will be directed
+into all REPLs simultaneously. See [Managing
+Connections](managing_connections.md) for more details.

doc/code_completion.md

@@ -18,29 +18,31 @@ dedicated buffer.
 
 ## Auto-completion
 
-CIDER users are advised to use [`company-mode`](http://company-mode.github.io/)
-to enable auto-completion inside of source code and REPL buffers.  To install
-`company-mode` do:
+While the standard Emacs tooling works just fine, we suggest that
+CIDER users consider using
+[`company-mode`](http://company-mode.github.io/) instead. Company mode
+can be used for auto-completion for both source code and REPL buffers.
+To install `company-mode`:
 
 <kbd>M-x</kbd> `package-install` <kbd>RET</kbd> `company` <kbd>RET</kbd>
 
-After installation, company can be turned on  globally, like so --
+After installation, you can turn on `company-mode` globally:
 
 ```el
 (global-company-mode)
 ```
 
--- or through mode-specific hooks:
+or through mode-specific hooks:
 
 ```el
 (add-hook 'cider-repl-mode-hook #'company-mode)
 (add-hook 'cider-mode-hook #'company-mode)
 ```
 
-When `company-mode` is thus enabled, it will receive completion information
-from `cider-complete-at-point`, and requires no additional setup or plugins.
+When `company-mode` is enabled, it will receive completion information
+from `cider-complete-at-point` and requires no additional setup or plugins.
 
-If you'd prefer to trigger completions manually you can add this to you config:
+If you'd prefer to trigger completions manually you can add this to your config:
 
 ```el
 (setq company-idle-delay nil) ; never start completions automatically
@@ -56,22 +58,25 @@ you can add this to your config:
 
 ### Fuzzy candidate matching
 
-By default `company-mode` will provide completion candidates with the assumption
-that whatever you've typed so far (e.g. `map-`) is a completion prefix (meaning
-you'd get only candidates that have `map-` in the beginnings of their names).
-You can get enhanced fuzzy completion with the CIDER-specific completion style
-by adding:
+By default `company-mode` will provide completion candidates with the
+assumption that whatever you've typed so far is a prefix of what
+you're really trying to type. For example, if you type `map-` then
+you'll only get completion candidates that have `map-` as the
+beginning of their names.  Sometimes, you don't know the exact prefix
+for the item you want to type. In this case, you can get
+CIDER-specific "fuzzy completion" by adding:
 
 ```el
 (add-hook 'cider-repl-mode-hook #'cider-company-enable-fuzzy-completion)
 (add-hook 'cider-mode-hook #'cider-company-enable-fuzzy-completion)
 ```
 
-Now `company-mode` will accept certain fuzziness when matching candidates
-against the prefix. For example, typing `mp` will show you `map-indexed` as one
-of the possible completion candidates, `cji` will complete to `clojure.java.io`,
-etc. Different completion examples are
-listed [here](https://github.com/alexander-yakushev/compliment/wiki/Examples).
+Now, `company-mode` will accept certain fuzziness when matching
+candidates against the prefix. For example, typing `mp` will show you
+`map-indexed` as one of the possible completion candidates and `cji`
+will complete to `clojure.java.io`. Different completion examples are
+shown
+[here](https://github.com/alexander-yakushev/compliment/wiki/Examples).
 
 ### Completion annotations