From: Erlend E. Aasland <erlend@python.org>
Date: Wed, 9 Aug 2023 07:25:25 +0000 (+0200)
Subject: [3.11] gh-86457: Add docs for Argument Clinic @text_signature directive (#107747... 
X-Git-Tag: v3.11.5~80
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=b0b26af822e601461988d0765cf7b33d3791ff2e;p=thirdparty%2FPython%2Fcpython.git

[3.11] gh-86457: Add docs for Argument Clinic @text_signature directive (#107747) (#107799)

(cherry picked from commit a9aeb99579f24bbce1dd553d605a5a5e2f37a3a2)

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
---

diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst
index d75ba8a19cff..23be8a7a85c0 100644
--- a/Doc/howto/clinic.rst
+++ b/Doc/howto/clinic.rst
@@ -1893,3 +1893,36 @@ blocks embedded in Python files look slightly different.  They look like this:
     #[python start generated code]*/
     def foo(): pass
     #/*[python checksum:...]*/
+
+
+.. _clinic-howto-override-signature:
+
+How to override the generated signature
+---------------------------------------
+
+You can use the ``@text_signature`` directive to override the default generated
+signature in the docstring.
+This can be useful for complex signatures that Argument Clinic cannot handle.
+The ``@text_signature`` directive takes one argument:
+the custom signature as a string.
+The provided signature is copied verbatim to the generated docstring.
+
+Example from :source:`Objects/codeobject.c`::
+
+   /*[clinic input]
+   @text_signature "($self, /, **changes)"
+   code.replace
+       *
+       co_argcount: int(c_default="self->co_argcount") = unchanged
+       co_posonlyargcount: int(c_default="self->co_posonlyargcount") = unchanged
+       # etc ...
+
+       Return a copy of the code object with new values for the specified fields.
+   [clinic start generated output]*/
+
+The generated docstring ends up looking like this::
+
+   replace($self, /, **changes)
+   --
+
+   Return a copy of the code object with new values for the specified fields.
diff --git a/Misc/NEWS.d/next/Tools-Demos/2023-08-07-16-30-48.gh-issue-95065.-im4R5.rst b/Misc/NEWS.d/next/Tools-Demos/2023-08-07-16-30-48.gh-issue-95065.-im4R5.rst
index 4768e6767574..7284f5bd5488 100644
--- a/Misc/NEWS.d/next/Tools-Demos/2023-08-07-16-30-48.gh-issue-95065.-im4R5.rst
+++ b/Misc/NEWS.d/next/Tools-Demos/2023-08-07-16-30-48.gh-issue-95065.-im4R5.rst
@@ -1,2 +1,2 @@
 Argument Clinic now supports overriding automatically generated signature by
-using directive ``@text_signature``.
+using directive ``@text_signature``. See :ref:`clinic-howto-override-signature`.