If it's source code, programmers will need to examine it from time to time.  A more important distinction imo: stringlib is type-parameterized like some sort of prehistoric C++ template specialization.  Thankfully the gunk generated by Argument Clinic is free of such dizzying technology.


Another approach to making Clinic output easier to read--which I thought I also proposed at one point--would be to save up most of the Clinic output in an "accumulator", then emit the contents of the accumulator on demand.  Clinic could probably get away with only generating a prototype for the generated function, the macro for the methoddef, and the prototype (sans semicolon) for the impl.  The bulk of the generated code, the implementation of the generated function and the docstring, would go in the "accumulator" and could be tucked away anywhere in the file you like.  I could even make it idiot-proof; if you haven't emptied the accumulator before the end of the file, it could tack the correct Clinic block on the end for you.

Here's a quick mockup of what that would look like:

/*[clinic]

    zlib.compress
        bytes: Py_buffer
            Binary data to be compressed.
        [
        level: int
            Compression level, in 0-9.
        ]
        /

    Returns compressed string.

    [clinic]*/

    #define ZLIB_COMPRESS_METHODDEF    \
        {"compress", (PyCFunction)zlib_compress, METH_VARARGS, zlib_compress__doc__},

    static PyObject *
    zlib_compress(PyModuleDef *module, PyObject *args);

    static PyObject *
    zlib_compress_impl(PyModuleDef *module, Py_buffer *bytes, int group_right_1, int level)
    /*[clinic checksum: 9f055a396620bc1a8a13d74c3496249528b32b0d]*/
    {
        PyObject *ReturnVal = NULL;
        Byte *input, *output = NULL;
        unsigned int length;
        ...


Not sure how far this suggestion ever got; I think maybe I only showed it to Stefan Krah, who said it wouldn't help his use case so I dropped it.

Any good?