docs: Document pitfall of deprecation pragmas
As we discovered in gtk#1280 (closed), GCC considers the pragmas to control the deprecation warnings as statements. This means we cannot just use the GLib wrappers as markers around the call site, but we must be aware of their side effects.
Let's document this, to avoid falling into the trap.