WIP: Cleanup documentation for 8.4.0

.gitignore

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

CHANGES.rst

@@ -17,6 +17,9 @@ Unreleased
         ``dict[str, Any]``.
     -   :class:`CompositeParamType` and the number-range base are now
         generic with abstract methods.
+-   Refactor ``convert_type`` to extract type inference into a private
+    ``_guess_type`` helper, and add :func:`typing.overload` signatures.
+    :pr:`3372`
 -   :class:`Parameter` typing improvements. :pr:`2805`
 
     -   :class:`Parameter` is now an abstract base class, making explicit
@@ -46,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`
 

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")