mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-07 13:28:19 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 9

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

Browse source 
- 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
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. Return a copy of the code object with new values for the specified fields.
[clinic start generated output]*/ [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__, .. code-block:: none
"replace($self, /, **changes)\n"
"--\n" replace($self, /, **changes)
"\n" --
"Return a copy of the code object with new values for the specified fields.");
Return a copy of the code object with new values for the specified fields.
.. _clinic-howto-deprecate-positional: .. _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. 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 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:: by adding the line ``* [from 3.14]`` right above the *b* parameter::
/*[clinic input] /*[clinic input]
@ -2000,12 +2001,12 @@ Luckily for us, compiler warnings are now generated:
.. code-block:: none .. code-block:: none
In file included from Modules/foomodule.c:139: 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] 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 "Update 'b' in 'myfunc' in 'foomodule.c' to be keyword-only." # 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; 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*:: with the ``*`` from the line above *c*::
/*[clinic input] /*[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 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`.