[Python-checkins] cpython (3.5): Issue 28753: Argument Clinic howto docfix, courtesy Julien Palard.

[martin.panter]

https://hg.python.org/cpython/rev/7a93d1a0a1cf
changeset:   105561:7a93d1a0a1cf
branch:      3.5
parent:      105517:d350fc4d78ff
user:        Martin Panter <vadmium+py at gmail.com>
date:        Sat Dec 10 03:49:12 2016 +0000
summary:
  Issue 28753: Argument Clinic howto docfix, courtesy Julien Palard.

files:
  Doc/howto/clinic.rst |  29 +++++++++++++++--------------
  1 files changed, 15 insertions(+), 14 deletions(-)


diff --git a/Doc/howto/clinic.rst b/Doc/howto/clinic.rst
--- a/Doc/howto/clinic.rst
+++ b/Doc/howto/clinic.rst
@@ -375,15 +375,12 @@
         Write a pickled representation of obj to the open file.
         [clinic start generated code]*/
 
-12. Save and close the file, then run ``Tools/clinic/clinic.py`` on it.
-    With luck everything worked and your block now has output!  Reopen
-    the file in your text editor to see::
+12. Save and close the file, then run ``Tools/clinic/clinic.py`` on
+    it.  With luck everything worked---your block now has output, and
+    a ``.c.h`` file has been generated! Reopen the file in your
+    text editor to see:
 
-       /*[clinic input]
-       module _pickle
-       class _pickle.Pickler "PicklerObject *" "&Pickler_Type"
-       [clinic start generated code]*/
-       /*[clinic end generated code: checksum=da39a3ee5e6b4b0d3255bfef95601890afd80709]*/
+    .. code-block:: c
 
        /*[clinic input]
        _pickle.Pickler.dump
@@ -395,18 +392,22 @@
        Write a pickled representation of obj to the open file.
        [clinic start generated code]*/
 
-       PyDoc_STRVAR(_pickle_Pickler_dump__doc__,
-       "Write a pickled representation of obj to the open file.\n"
-       "\n"
-       ...
        static PyObject *
-       _pickle_Pickler_dump_impl(PicklerObject *self, PyObject *obj)
-       /*[clinic end generated code: checksum=3bd30745bf206a48f8b576a1da3d90f55a0a4187]*/
+       _pickle_Pickler_dump(PicklerObject *self, PyObject *obj)
+       /*[clinic end generated code: output=87ecad1261e02ac7 input=552eb1c0f52260d9]*/
 
     Obviously, if Argument Clinic didn't produce any output, it's because
     it found an error in your input.  Keep fixing your errors and retrying
     until Argument Clinic processes your file without complaint.
 
+    For readability, most of the glue code has been generated to a ``.c.h``
+    file.  You'll need to include that in your original ``.c`` file,
+    typically right after the clinic module block:
+
+     .. code-block:: c
+
+       #include "clinic/_pickle.c.h"
+
 13. Double-check that the argument-parsing code Argument Clinic generated
     looks basically the same as the existing code.
 

-- 
Repository URL: https://hg.python.org/cpython