Cleanup #3126

Link to PR in changelog, move implementation details to Python code, fix changed version and align `.gitignore` syntax

Author: kdeldycke

.gitignore

@@ -6,4 +6,4 @@ dist/
 htmlcov/
 .tox/
 docs/_build/
-.venv
+.venv/

CHANGES.rst

@@ -49,7 +49,7 @@ Unreleased
     replacing the ``start`` built-in which cannot be invoked without
     ``shell=True``. :issue:`3164` :pr:`3186`
 -   Fix Fish shell completion errors when option help text contains newlines.
-    :issue:`3043`
+    :issue:`3043` :pr:`3126`
 -   Add :class:`NoSuchCommand` exception with suggestions for misspelled
     commands. :issue:`3107` :pr:`3228`
 -   Add ``click.get_pager_file`` for file-like access to an output

src/click/shell_completion.py

@@ -421,15 +421,16 @@ def get_completion_args(self) -> tuple[list[str], str]:
         return args, incomplete
 
     def format_completion(self, item: CompletionItem) -> str:
-        """Format completion item for Fish shell.
-
-        Escapes newlines in both value and help text to prevent
-        Fish shell parsing errors.
-
-        .. versionchanged:: 8.3
-            Escape newlines in help text to fix completion errors
-            with multi-line help strings.
         """
+        .. versionchanged:: 8.4
+            Escape newlines in value and help to fix completion errors with
+            multi-line help strings.
+        """
+        # The fish completion script splits each response line on literal
+        # newlines, so any newline in the value or help would corrupt the
+        # frame. Replace them with the two-character escape "\n" so the text
+        # round-trips through fish without breaking the format. The "_"
+        # sentinel for missing help mirrors :class:`ZshComplete`.
         help_ = item.help or "_"
         value = item.value.replace("\n", r"\n")
         help_escaped = help_.replace("\n", r"\n")