Improve params documentation

docs/cli.md

@@ -223,16 +223,38 @@ These commands will execute two different project revisions based on the given G
 
 ### Pipeline parameters
 
-Pipeline scripts can use an arbitrary number of parameters that can be overridden using the command line or Nextflow configuration files. Any script parameter can be specified on the command line by prefixing the parameter name with double-dash characters. For example:
+Pipeline scripts can define *parameters* which can be overridden on the command line.
+
+Parameters can be declared in the main script:
+
+```nextflow
+params.alpha = 'default script value'
+
+workflow {
+  println "alpha = ${params.alpha}"
+}
+```
+
+Or in a config file:
+
+```groovy
+params {
+  alpha = 'default config value'
+}
+```
+
+The above parameter can be specified on the command line as `--alpha`:
 
 ```console
-$ nextflow run <pipeline> --foo Hello
+$ nextflow run <pipeline> --alpha Hello
 ```
 
-Then, the parameter can be accessed in the pipeline script using the `params.foo` identifier.
+:::{note}
+Parameters that are specified on the command line without a value are set to `true`.
+:::
 
 :::{note}
-When the parameter name is formatted using `camelCase`, a second parameter is created with the same value using `kebab-case`, and vice versa.
+Parameters that are specified on the command line with `kebab-case` names are automatically converted to `camelCase`. For exapmle, a parameter defined as `fooBar` in the pipeline script can be given on the command line as `--fooBar` or `--foo-bar`.
 :::
 
 :::{warning}
@@ -245,14 +267,14 @@ $ nextflow run <pipeline> --files "*.fasta"
 
 Parameters specified on the command line can be also specified in a params file using the `-params-file` option.
 
-```bash
-nextflow run main.nf -params-file pipeline_params.yml
+```console
+$ nextflow run main.nf -params-file pipeline_params.yml
 ```
 
 The `-params-file` option loads parameters for your Nextflow pipeline from a JSON or YAML file. Parameters defined in the file are equivalent to specifying them directly on the command line. For example, instead of specifying parameters on the command line:
 
-```bash
-nextflow run main.nf --alpha 1 --beta foo
+```console
+$ nextflow run main.nf --alpha 1 --beta foo
 ```
 
 Parameters can be represented in YAML format:
@@ -271,7 +293,12 @@ Or in JSON format:
 }
 ```
 
-The parameters specified in a params file are merged with the resolved configuration. The values provided via a params file overwrite those of the same name in the Nextflow configuration file, but not those specified on the command line.
+Parameters are applied in the following order (from lowest to highest priority):
+
+1. Parameters defined in pipeline scripts (e.g. `main.nf`)
+2. Parameters defined in {ref}`config files <config-params>`
+6. Parameters specified in a params file (`-params-file`)
+7. Parameters specified on the command line (`--something value`)
 
 ## Managing projects
 

docs/config.md

@@ -6,18 +6,13 @@
 
 When a pipeline script is launched, Nextflow looks for configuration files in multiple locations. Since each configuration file may contain conflicting settings, they are applied in the following order (from lowest to highest priority):
 
-1. Parameters defined in pipeline scripts (e.g. `main.nf`)
-2. The config file `$HOME/.nextflow/config`, or `$NXF_HOME/.nextflow/config` when `NXF_HOME` is set (see [`NXF` prefixed variables](reference/env-vars.html#nextflow-settings)).
-3. The config file `nextflow.config` in the project directory
-4. The config file `nextflow.config` in the launch directory
-5. Config file specified using the `-c <config-file>` option
-6. Parameters specified in a params file (`-params-file` option)
-7. Parameters specified on the command line (`--something value`)
-
-When more than one of these options for specifying configurations are used, they are merged, so that the settings in the first override the same settings appearing in the second, and so on.
+1. The config file `$HOME/.nextflow/config` (or `$NXF_HOME/.nextflow/config` when {ref}`NXF_HOME <nxf-env-vars>` is set).
+2. The config file `nextflow.config` in the project directory
+3. The config file `nextflow.config` in the launch directory
+4. Config files specified using the `-c <config-files>` option
 
 :::{tip}
-You can use the `-C <config-file>` option to use a single configuration file and ignore all other files.
+You can alternatively use the `-C <config-file>` option to specify a fixed set of configuration files and ignore all other files.
 :::
 
 (config-syntax)=
@@ -129,16 +124,16 @@ The following functions are globally available in a Nextflow configuration file:
 Pipeline parameters can be defined in the config file using the `params` scope:
 
 ```groovy
-params.custom_param = 123
-params.another_param = 'string value .. '
+params.alpha = 123
+params.beta = 'string value .. '
 
 params {
-    alpha_1 = true
-    beta_2 = 'another string ..'
+    gamma = true
+    delta = "params.alpha is ${params.alpha}"
 }
 ```
 
-See {ref}`cli-params` for information about how to modify these on the command line.
+See {ref}`cli-params` for information about how to specify pipeline parameters.
 
 (config-process)=
 

docs/reference/env-vars.md

@@ -12,6 +12,8 @@ The following environment variables control the configuration of the Nextflow ru
 `JAVA_HOME`
 : Defines the path location of the Java VM installation used to run Nextflow.
 
+(nxf-env-vars)=
+
 ## Nextflow settings
 
 `NXF_ANSI_LOG`