Argument Clinic: make error messages more helpful to developers

[erlend-aasland]

Some¹ of the Argument Clinic error messages only point to the problem in the clinic input, but do not suggest how to fix it. Suggesting to do an audit of clinic.py and improve the error messages that are too implicit or provide too little information/context to the developer.

Random selection of error messages that might be improved:

• "Too many var args" (how many are there now? what is too many?)
• "Not enough arguments for destination {name!r} new {type!r}" (how many arguments are expected, and what kind of arguments are they?)
• "Can't clear destination {name!r}: it's not of type 'buffer'" (what type is it?)
• "Custom printers are broken right now"
• "bool_converter: illegal 'accept' argument {accept!r}" (why is it illegal? how to fix this?)
• "char_converter: illegal default value {default!r}" (which values are legal? how to fix this?)
• "illegal combination of arguments""
• "'kind' of function and cloned function don't match! (@classmethod/@staticmethod/@coexist)" (what was the mismatch?)

(There might be better examples; this was the result of a very quick and short audit.)

cc. @sobolevn

Linked PRs

• gh-115077: Make some Argument Clinic error messages more helpful #115078
• gh-115077: Argument Clinic: generate better error messages when parsing function declaration #115555

Footnotes

1. but, definitely not all! ↩

[erlend-aasland]

Suggested by @sobolevn in #114930 (comment).

[sobolevn]

What do you think: is it better to work on this one-by-one or in bulk?

[erlend-aasland]

There's also the possibility of always including the offending line, thus making these error messages look more like tracebacks:

Error in file 'test.c' on line 2:
    fn:
    ^
Illegal function name.

[erlend-aasland]

What do you think: is it better to work on this one-by-one or in bulk?

One-by-one is too fine-grained, IMO; I think batches are fine. For example, all the converters in one PR and all the return converters in another.

[serhiy-storchaka]

I would try to do this in one piece. It may expose some patterns and lead to better structure of the code and tests.

But is some cases cannot be easily improved, I would left them out. And if some cases require significant rewriting, they can be split in a separate PR. You cannot say if this is needed before you try.

[erlend-aasland]

+1, @serhiy-storchaka. BTW, feel free to contribute to my draft PR, if you wish.