> As for the docstring: I would like it better if I could avoid typing
> the cumbersome "\n\"s.

I agree with Stefan that the file is a lot more readable if the docstring
is not repeated twice. It's unfortunate that C doesn't have a notion of
a raw string (as opposed to C++11 with the new R"(...)" syntax) but I
think it is something we'll have to live with. I would have expected
that a good text editor would be able to convert a selected region into a
C string, but I've never actually seen such a feature.

In general I think we should aim for clarity in scope of the arguments in
the DSL -- either by using curly-braces (a C construct) or indentation (a
Python construct). To minimize the usage of vertical space, I'd like to
see the DSL not require a blank line between arguments.

In a project I worked on recently I ended up writing a parser to go
through a list of C arguments and automatically produce the
PyArg_ParseTuple / PyArg_ParseTupleAndKeywords lines. It's not as
full featured as what we are looking for here, but it did have the
benefit of minimizing the number of extra vertical lines.  For example::

    static PyObject *
    w_rktime(PyObject *self, PyObject *args, PyObject *kwargs)
    {
        /*[kwargs rktime]*/
        darray u;
        meshdata msh;
        double dt;
        int nsteps=1;
        /*[/kwargs]*/
        static char *_keywords[] = {"u", "msh", "dt", "nsteps", NULL};
        if (!PyArg_ParseTupleAndKeywords(args, kwargs, "O&O&d|i:rktime", _keywords, view_as_darray, &u, DgMeshData_Converter, &msh, &dt, &nsteps))
            return NULL;
        /*[checksum=...]*/
        ...
    }

I could imagine extending such a syntax to allow custom converters
and other extensions using comments::

    path_t path = PATH_T_INITIALIZE("stat", 0, 1)
        /* converter = path_converter; default = None */;
    int dir_fd = DEFAULT_DIR_FD
        /* converter = OS_STAT_DIR_FD_CONVERTER */;

The biggest downside to this approach would be that the parser could
not inject C code directly into the global scope -- instead it would
be limited to producing #define lines.

-Brad