C domain: reconsider treating `complex` as a C keyword.

[mdickinson]

According to issue 44426 reported on bugs.python.org, Sphinx 4.0.2 fails to build the current Python documentation (when warnings are being treated as errors) as a result of this warning:

Warning, treated as error:
/builddir/build/BUILD/Python-3.10.0b2/Doc/c-api/complex.rst:49:Error in declarator or parameters
Error in declarator or parameters
Invalid C declaration: Expected identifier, got keyword: complex [error at 39]
  Py_complex _Py_c_neg(Py_complex complex)
  ---------------------------------------^
make: *** [Makefile:51: build] Error 2

This issue has been worked around in the CPython source, by changing the name complex to num. Nevertheless, I think Sphinx is being too strict here, and the error message is incorrect: complex is not a C keyword. If complex.h has been included, then complex is a macro that expands to a C keyword, but that's not the same thing, and there's plenty of code out there that doesn't include complex.h (CPython doesn't include complex.h at any point, for example) and may still want to use complex as a C variable name.

Both gcc and clang are happy for complex to be used as a variable name, and don't issue any warning:

mdickinson@mirzakhani Desktop % cat test.c
typedef struct {
    double real;
    double imag;
} Py_complex;

Py_complex _Py_c_neg(Py_complex complex);
mdickinson@mirzakhani Desktop % gcc -Wall -Wextra -std=c17 -c test.c
mdickinson@mirzakhani Desktop % clang -Wall -Wextra -std=c17 -c test.c
mdickinson@mirzakhani Desktop %

[jakobandersen]

That is indeed right, that keyword list was done a bit too quickly.
None of the convenience macros should be hard-coded keywords, though I'm thinking of making them user-configurable keywords so each project can decide which of them they use, e.g., through a config variable like c_extra_keywords. Would that work for CPython?
If so, any opinions on which should be the default ones (of alignas, alignof, bool, complex, imaginary, noreturn, static_assert, thread_local)? all of them? or are there any that are often used as names?

[mdickinson]

Would that work for CPython?

CPython's happy at this point: complex wasn't a great variable name in the first place, and the declaration in the docs didn't even match what was used in the actual source, so changing it wasn't a hard choice. I was mostly opening this issue for awareness, and in case other projects might run into this.

Not sure I can comment on the usefulness or potential default contents of something like c_extra_keywords: sounds like a fine idea, but I suspect CPython itself wouldn't benefit. I'd probably go for either all of them or none of them as a default, rather than picking and choosing, just for simplicity.

[jakobandersen]

The c_extra_keywords has been added for the next release. As default all the "keywords" from macros are in the list.