homepage

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.