Document environment() append/prepend/set with multiple values [skip ci]

Fixes https://github.com/mesonbuild/meson/issues/3761

1 files changed, 15 insertions, 12 deletions

diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index bab20e1..87fb581 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -1991,20 +1991,23 @@ detailed information about how environment variables should be set
 during tests. It should be passed as the `env` keyword argument to
 tests. It has the following methods.
 
-- `append(varname, value)` appends the given value to the old value of
-  the environment variable, e.g.  `env.append('FOO', 'BAR', separator
-  : ';')` produces `BOB;BAR` if `FOO` had the value `BOB` and plain
-  `BAR` if the value was not defined. If the separator is not
-  specified explicitly, the default path separator for the host
-  operating system will be used, i.e. ';' for Windows and ':' for
-  UNIX/POSIX systems.
-
-- `prepend(varname, value)` is the same as `append` except that it
+- `append(varname, value1, value2, ...)` appends the given values to the old
+  value of the environment variable, e.g.  `env.append('FOO', 'BAR', 'BAZ',
+  separator : ';')` produces `BOB;BAR;BAZ` if `FOO` had the value `BOB` and
+  plain `BAR;BAZ` if the value was not defined. If the separator is not
+  specified explicitly, the default path separator for the host operating
+  system will be used, i.e. ';' for Windows and ':' for UNIX/POSIX systems.
+
+- `prepend(varname, value1, value2, ...)` is the same as `append` except that it
   writes to the beginning of the variable
 
-- `set(varname, value)` sets environment variable in the first
-  argument to the value in the second argument, e.g.
-  `env.set('FOO', 'BAR')` sets envvar `FOO` to value `BAR`
+- `set(varname, value1, value2)` sets the environment variable specified in the
+  first argument to the values in the second argument joined by the separator,
+  e.g.  `env.set('FOO', 'BAR'),` sets envvar `FOO` to value `BAR`. See
+  `append()` above for how separators work.
+
+**Note:** All these methods overwrite the previously-defined value(s) if called
+twice with the same `varname`.
 
 ### `external library` object