Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

Docs: clean up Argument Clinic howto's (#107797) 

- fix formatting in @text_signature howto and NEWS entry
- fix formatting and example text in deprecate-positionals howto
This commit is contained in:
Erlend E. Aasland 2023-08-09 09:43:02 +02:00 committed by GitHub
parent 925bbc2166
commit 34cafd35e3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 12 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
Doc/howto/clinic.rst
View File

@ -1930,13 +1930,14 @@ Example from :source:`Objects/codeobject.c`::
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::
The generated docstring ends up looking like this:
Doc_STRVAR(code_replace__doc__,
"replace($self, /, **changes)\n"
"--\n"
"\n"
"Return a copy of the code object with new values for the specified fields.");
.. code-block:: none
replace($self, /, **changes)
--
Return a copy of the code object with new values for the specified fields.
.. _clinic-howto-deprecate-positional:
@ -1968,7 +1969,7 @@ whenever the *b* parameter is passed positionally,
and we'll be allowed to make it keyword-only in Python 3.14 at the earliest.
We can use Argument Clinic to emit the desired deprecation warnings
using the ``* [from ...]``` syntax,
using the ``* [from ...]`` syntax,
by adding the line ``* [from 3.14]`` right above the *b* parameter::
/*[clinic input]
@ -2000,12 +2001,12 @@ Luckily for us, compiler warnings are now generated:
.. code-block:: none
In file included from Modules/foomodule.c:139:
Modules/clinic/foomodule.c.h:83:8: warning: Update 'b' in 'myfunc' in 'foomodule.c' to be keyword-only. [-W#warnings]
# warning "Update 'b' in 'myfunc' in 'foomodule.c' to be keyword-only."
Modules/clinic/foomodule.c.h:139:8: warning: In 'foomodule.c', update parameter(s) 'a' and 'b' in the clinic input of 'mymod.myfunc' to be keyword-only. [-W#warnings]
# warning "In 'foomodule.c', update parameter(s) 'a' and 'b' in the clinic input of 'mymod.myfunc' to be keyword-only. [-W#warnings]"
^
We now close the deprecation phase by making *b* keyword-only;
replace the ``* [from ...]``` line above *b*
replace the ``* [from ...]`` line above *b*
with the ``*`` from the line above *c*::
/*[clinic input]

2
Misc/NEWS.d/next/Tools-Demos/2023-08-07-16-30-48.gh-issue-95065.-im4R5.rst
View File

@ -1,2 +1,2 @@
Argument Clinic now supports overriding automatically generated signature by
using directive `@text_signature`. See :ref:`clinic-howto-override-signature`.
using directive ``@text_signature``. See :ref:`clinic-howto-override-signature`.