Improve docs for string join

doc_src/cmds/string-join.rst

@@ -8,8 +8,8 @@ Synopsis
 
 .. synopsis::
 
-    string join [-q | --quiet] SEP [STRING ...]
-    string join0 [-q | --quiet] [STRING ...]
+    string join [-q | --quiet] [-n | --no-empty] [--] SEP [STRING ...]
+    string join0 [-q | --quiet] [-n | --no-empty] [--] [STRING ...]
 
 .. END SYNOPSIS
 
@@ -18,11 +18,28 @@ Description
 
 .. BEGIN DESCRIPTION
 
-``string join`` joins its *STRING* arguments into a single string separated by *SEP*, which can be an empty string. Exit status: 0 if at least one join was performed, or 1 otherwise. If ``-n`` or ``--no-empty`` is specified, empty strings are excluded from consideration (e.g. ``string join -n + a b "" c`` would expand to ``a+b+c`` not ``a+b++c``).
+Joins its *STRING* arguments into a single string separated by *SEP* (for ``string join``) or by the
+zero byte (NUL) (for ``string join0``).
+Exit status: 0 if at least one join was performed, or 1 otherwise.
 
-``string join0`` joins its *STRING* arguments into a single string separated by the zero byte (NUL), and adds a trailing NUL. This is most useful in conjunction with tools that accept NUL-delimited input, such as ``sort -z``. Exit status: 0 if at least one join was performed, or 1 otherwise.
+**-n**, **--no-empty**
+    Exclude empty strings from consideration (e.g. ``string join -n + a b "" c`` would expand to ``a+b+c`` not ``a+b++c``).
 
-Because Unix uses NUL as the string terminator, passing the output of ``string join0`` as an *argument* to a command (via a :ref:`command substitution <expand-command-substitution>`) won't actually work. Fish will pass the correct bytes along, but the command won't be able to tell where the argument ends. This is a limitation of Unix' argument passing.
+**-q**, **--quiet**
+    Do not print the strings, only set the exit status as described above.
+
+**WARNING**:
+Insert a  ``--`` before positional arguments to prevent them from being interpreted as flags.
+Otherwise, any strings starting with ``-`` will be treated as flag arguments, meaning they will most likely result in the command failing.
+This is also true if you specify a variable which expands to such a string instead of a literal string.
+If you don't need to append flag arguments at the end of the command,
+just always use ``--`` to avoid unwelcome surprises.
+
+``string join0`` adds a trailing NUL. This is most useful in conjunction with tools that accept NUL-delimited input, such as ``sort -z``.
+
+Because Unix uses NUL as the string terminator, passing the output of ``string join0`` as an *argument* to a command (via a :ref:`command substitution <expand-command-substitution>`) won't actually work.
+Fish will pass the correct bytes along, but the command won't be able to tell where the argument ends.
+This is a limitation of Unix' argument passing.
 
 .. END DESCRIPTION
 
@@ -43,4 +60,14 @@ Examples
     >_ string join '' a b c
     abc
 
+    >_ set -l markdown_list '- first' '- second' '- third'
+    # Strings with leading hyphens (also in variable expansions) are interpreted as flag arguments by default.
+    >_ string join \n $markdown_list
+    string join: - first: unknown option
+    # Use '--' to prevent this.
+    >_ string join -- \n $markdown_list
+    - first
+    - second
+    - third
+
 .. END EXAMPLES

doc_src/cmds/string.rst

@@ -11,7 +11,7 @@ Synopsis
     string collect [-a | --allow-empty] [-N | --no-trim-newlines] [STRING ...]
     string escape [-n | --no-quoted] [--style=] [STRING ...]
     string join [-q | --quiet] [-n | --no-empty] SEP [STRING ...]
-    string join0 [-q | --quiet] [STRING ...]
+    string join0 [-q | --quiet] [-n | --no-empty] [STRING ...]
     string length [-q | --quiet] [STRING ...]
     string lower [-q | --quiet] [STRING ...]
     string match [-a | --all] [-e | --entire] [-i | --ignore-case]
@@ -27,7 +27,7 @@ Synopsis
                    [-r | --regex] [-q | --quiet] PATTERN REPLACE [STRING ...]
     string shorten [(-c | --char) CHARS] [(-m | --max) INTEGER]
                    [-N | --no-newline] [-l | --left] [-q | --quiet] [STRING ...]
-    string split [(-f | --fields) FIELDS] [(-m | --max) MAX] [-n | --no-empty] 
+    string split [(-f | --fields) FIELDS] [(-m | --max) MAX] [-n | --no-empty]
                  [-q | --quiet] [-r | --right] SEP [STRING ...]
     string split0 [(-f | --fields) FIELDS] [(-m | --max) MAX] [-n | --no-empty]
                   [-q | --quiet] [-r | --right] [STRING ...]