Improve clarity of user-facing documentation

Author: penelopeysm

docs/src/api.md

@@ -92,32 +92,45 @@ To ensure that sampling multiple chains "just works" when sampling of a single c
 
 ## Progress logging
 
-The default value for the `progress` keyword argument is `AbstractMCMC.PROGRESS[]`, which is always set to `true` unless modified with `AbstractMCMC.setprogress!`.
-For example, `setprogress!(false)` will disable all progress logging.
+Progress logging is controlled in one of two ways:
 
-```@docs
-AbstractMCMC.setprogress!
-```
+- by passing the `progress` keyword argument to the `sample(...)` function, or
+- by globally changing the defaults with `AbstractMCMC.setprogress!` and `AbstractMCMC.setmaxchainsprogress!`.
+
+### `progress` keyword argument
 
 For single-chain sampling (i.e., `sample([rng,] model, sampler, N)`), as well as multiple-chain sampling with `MCMCSerial`, the `progress` keyword argument should be a `Bool`.
 
 For multiple-chain sampling using `MCMCThreads`, there are several, more detailed, options:
 
-- `:perchain`: create one progress bar per chain being sampled
+- `:perchain`: create one progress bar per chain being sampled, plus one progress bar tracking the number of chains
 - `:overall`: create one progress bar for the overall sampling process, which tracks the percentage of samples that have been sampled across all chains
 - `:none`: do not create any progress bar
 - `true` (the default): use `perchain` for 10 or fewer chains, and `overall` for more than 10 chains
 - `false`: same as `none`, i.e. no progress bar
 
-The threshold of 10 chains can be changed using `AbstractMCMC.setmaxchainsprogress!(N)`, which will cause `MCMCThreads` to use `:perchain` for `N` or fewer chains, and `:overall` for more than `N` chains.
-Thus, for example, if you _always_ want to use `:overall`, you can call `AbstractMCMC.setmaxchainsprogress!(0)`.
-
 Multiple-chain sampling using `MCMCDistributed` behaves the same as `MCMCThreads`, except that `:perchain` is not (yet?) implemented.
 So, `true` always corresponds to `:overall`, and `false` corresponds to `:none`.
 
 !!! warning "Do not override the `progress` keyword argument"
     If you are implementing your own methods for `sample(...)`, you should make sure to not override the `progress` keyword argument if you want progress logging in multi-chain sampling to work correctly, as the multi-chain `sample()` call makes sure to specifically pass custom values of `progress` to the single-chain calls.
 
+### Global settings
+
+If you are sampling multiple times and would like to change the default behaviour, you can use these functions to control progress logging globally:
+
+```@docs
+AbstractMCMC.setprogress!
+AbstractMCMC.setmaxchainsprogress!
+```
+
+`setprogress!` is more general, and applies to all types of sampling (both single- and multiple-chain).
+It only takes a boolean argument, which switches progress logging on or off.
+For example, `setprogress!(false)` will disable all progress logging.
+
+On the other hand, `setmaxchainsprogress!` is specific to multiple-chain sampling, and allows you to set the threshold for when to switch from `:perchain` to `:overall` progress logging.
+Thus, for example, if you want to keep progress logging on but _always_ want to use `:overall`, you can set `AbstractMCMC.setmaxchainsprogress!(0)`.
+
 ## Chains
 
 The `chain_type` keyword argument allows to set the type of the returned chain. A common