Jim Jewett <report@bugs.python.org> wrote:
> (1)  The first several lines ( "/* pymacro.h */" until "/* could go into a separate header file */" ) would not be written at all, and are just there to help reviewers understand.

Yes, they should ultimately go into Include/pymacro.h.

> (2)  The "#define OS_STAT_DOC ..." line is the docstring, and would be needed, but could easily go into a separate header file, like os_stat__doc.h.  For something like cdecimal, there might be only a single _cdecimal__doc.h containing all the docstrings.  There might even be a build switch that (at a minimum) replaced anything from those __doc.h files with "" for space-constrained builds.

Yes, it's supposed to be the main part of the docstring. The docstring header
containing the function signature would be autogenerated.

> (3)  The human-maintained code would be the DSL between "/*[preprocessor]" and "[preprocessor]*/".

Yes.

> (4)  The lines between "[preprocessor]*/" and "/*[preprocessor end:f3e6b328245207c240825782d908d3ff3a9c11c0]*/" would NOT be written or maintained by a human, but WOULD be checked into hg for the benefit builders without the argument-clinic tool.

Yes, all that code would be generated by clinic.py.

> (5)  The only C code written or maintained by a human (or another macro system) would be the last 5 lines (the system call, the path cleanup, and the return).

Correct.

> If I'm correct, then your proposal boils down to
> 
> (1)  Allow (require?) the function-level docstring to be defined somewhere else, possibly in another file.

Yes.

> (2)  Change the DSL
>   (2a)  Get rid of function flags?  (Not sure this is workable)

I didn't intend to but you're right, they were missing.

>   (2b)  Replace the (previously proposed) parameter declarations with literal C code forming an array of [parameter kind, array-of-setup-instructions-and-or-magically-named-variable-settings]

Regarding the DSL: I wanted to change the syntax, not the functionality.
Unfortunately, as Antoine pointed out, I didn't get it quite right.

(2b): Perhaps I misunderstand, but the snippets of literal C code are also
present in Larry's original:

/*[clinic]
os.stat -> stat result

    path_t path = PATH_T_INITIALIZE("stat", 0, 1);
    required
    converter=path_converter

    int dir_fd = DEFAULT_DIR_FD;
    default=None
    converter=OS_STAT_DIR_FD_CONVERTER
    keyword-only

    int follow_symlinks = 1;
    default=True
    types=bool
[clinic]*/

The motivation for trying to change the DSL is that I'd like to see
a) something that looks more like a C declaration, b) something that
is easily compressible vertically and c) some visual hints that
subdivide the declaration into sections.