[glib/deprecated-pragma-docs: 836/836] docs: Document pitfall of deprecation pragmas

[Philip Withnall <pwithnall src gnome org>]

commit 50dcccc5040ec0530f03be5dd866a607dcb7df7c
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Thu Dec 13 16:38:38 2018 +0000

    docs: Document pitfall of deprecation pragmas
    
    As we discovered in GNOME/gtk#1280, 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.

 glib/docs.c | 39 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 38 insertions(+), 1 deletion(-)
---
diff --git a/glib/docs.c b/glib/docs.c
index 5d09f433e..f68a1a8b7 100644
--- a/glib/docs.c
+++ b/glib/docs.c
@@ -2021,7 +2021,44 @@
  * has any effect.)
  *
  * This macro can be used either inside or outside of a function body,
- * but must appear on a line by itself.
+ * but must appear on a line by itself. Both this macro and the corresponding
+ * %G_GNUC_END_IGNORE_DEPRECATIONS are considered statements, so they
+ * should not be used around branching or loop conditions; for instance,
+ * this use is invalid:
+ *
+ * |[<!-- language="C" -->
+ *   G_GNUC_BEGIN_IGNORE_DEPRECATIONS
+ *   if (check == some_deprecated_function ())
+ *   G_GNUC_END_IGNORE_DEPRECATIONS
+ *     {
+ *       do_something ();
+ *     }
+ * ]|
+ *
+ * and you should move the deprecated section outside the condition
+ *
+ * |[<!-- language="C" -->
+ *
+ *   // Solution A
+ *   some_data_t *res;
+ *
+ *   G_GNUC_BEGIN_IGNORE_DEPRECATIONS
+ *   res = some_deprecated_function ();
+ *   G_GNUC_END_IGNORE_DEPRECATIONS
+ *
+ *   if (check == res)
+ *     {
+ *       do_something ();
+ *     }
+ *
+ *   // Solution B
+ *   G_GNUC_BEGIN_IGNORE_DEPRECATIONS
+ *   if (check == some_deprecated_function ())
+ *     {
+ *       do_something ();
+ *     }
+ *   G_GNUC_END_IGNORE_DEPRECATIONS
+ * ]|
  *
  * |[<!-- language="C" --
  * static void