Annotate deprecations at function level

[chrysn]

Description

Functions are currently deprecated by documentation.

Nobody reads that.

C23 has __deprecated__, we should use that everywhere, maybe even CI-test for Doxygen-deprecation without C-deprecation, and verify that at least some compiler complains loudly when a deprecated function is used.

This should help us make our deprecation process more trustworthy.

Next steps

• Add attribute everywhere
• Add defines to unbreak any compilers that don't like it.
• Check which compilers now give warnings / errors.

[chrysn]

Good news from early experimentation: -Wno-error=deprecated-declarations allows accepting the use of deprecated functions.

Bad news: GCC only accepts C2x attributes if an appropriate std= is used. We can't get away with just no-error'ing it, because "ISO C does not support ‘[[]]’ attributes before C2X" is a -Wpedantic thing, so we can't just allow it selectively -- even if we hid the attribute behind a macro.

This shouldn't stop us, though: We could still make the DEPRECARTED macro expand empty unless __STDC_VERSION__ > 202000L. And then, once anyone sets -std=gnu2x, they get the deprecation errors.

A workaround may be defining it as __attribute__((deprecated)); this works also for GCC when older std versions are used. Occasionally testing code with new std= versions will ensure that it is only added in places where the C2x deprecation is legal.

On the Doxygen side, if we just defined this as in C2x, we'd see the macro in the function signature (showing as DEPRECATED void foo_bar(void)) -- but if the line "DEPRECATED(x):=/** \deprecated x */" is added to the Doxygen PREDEFINED list (with the := and \ details being the only combination that works), the deprecation message is even printed in Doxygen, with the only small blemish that the quotation marks become part of the deprecation box -- I can live with that. [edit: And Doxygen links a la @ref or \ref will not work in there. Still OK IMO].