[gtk+] Add some documentation around deprecations

[Matthias Clasen <matthiasc src gnome org>]

commit f6d8c8a717851c282c90b168492e9c5ee23cfc80
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Feb 27 07:56:29 2012 -0500

    Add some documentation around deprecations

 docs/reference/gdk/gdk3-sections.txt |   10 +++++++++-
 docs/reference/gtk/Makefile.am       |    1 +
 docs/reference/gtk/compiling.sgml    |   10 +++++++++-
 docs/reference/gtk/gtk-docs.sgml     |    2 +-
 gdk/gdk.c                            |   22 +++++++++++++++++++++-
 gdk/gdkversionmacros.h.in            |    8 ++++++++
 6 files changed, 49 insertions(+), 4 deletions(-)
---
diff --git a/docs/reference/gdk/gdk3-sections.txt b/docs/reference/gdk/gdk3-sections.txt
index 9756518..9d63807 100644
--- a/docs/reference/gdk/gdk3-sections.txt
+++ b/docs/reference/gdk/gdk3-sections.txt
@@ -52,6 +52,14 @@ GDK_WINDOWING_X11
 GDK_WINDOWING_WIN32
 GDK_WINDOWING_QUARTZ
 
+<SUBSECTION>
+GDK_VERSION_3_0
+GDK_VERSION_3_2
+GDK_VERSION_3_4
+GDK_VERSION_MIN_REQUIRED
+GDK_VERSION_MAX_ALLOWED
+GDK_DISABLE_DEPRECATION_WARNINGS
+
 <SUBSECTION Standard>
 GDK_TYPE_GRAB_STATUS
 
@@ -1135,4 +1143,4 @@ gdk_app_launch_context_get_type
 gdk_test_render_sync
 gdk_test_simulate_button
 gdk_test_simulate_key
-</SECTION>
+
diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am
index 5099c33..b0083fc 100644
--- a/docs/reference/gtk/Makefile.am
+++ b/docs/reference/gtk/Makefile.am
@@ -142,6 +142,7 @@ content_files =					\
 	overview.xml
 
 expand_content_files = 				\
+	compiling.sgml				\
 	drawing-model.xml			\
 	getting_started.xml			\
 	glossary.xml				\
diff --git a/docs/reference/gtk/compiling.sgml b/docs/reference/gtk/compiling.sgml
index f4021c6..03206d9 100644
--- a/docs/reference/gtk/compiling.sgml
+++ b/docs/reference/gtk/compiling.sgml
@@ -51,11 +51,19 @@ Deprecated GTK+ functions are annotated to make the compiler
 emit warnings when they are used (e.g. with gcc, you need to use
 the -Wdeprecated-declarations option). If these warnings are
 problematic, they can be turned off by defining the preprocessor
-symbol GDK_DISABLE_DEPRECATION_WARNINGS by using the commandline
+symbol %GDK_DISABLE_DEPRECATION_WARNINGS by using the commandline
 option <literal>-DGDK_DISABLE_DEPRECATION_WARNINGS</literal>
 </para>
 
 <para>
+GTK+ deprecation annotations are versioned; by defining the
+macros %GDK_VERSION_MIN_REQUIRED and %GDK_VERSION_MAX_ALLOWED,
+you can specify the range of GTK+ versions whose API you want
+to use. APIs that were deprecated before or introduced after
+this range will trigger compiler warnings.
+</para>
+
+<para>
 The older deprecation mechanism of hiding deprecated interfaces
 entirely from the compiler by using the preprocessor symbol
 GTK_DISABLE_DEPRECATED is still used for deprecated macros,
diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index c435070..f3e744a 100644
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -23,7 +23,7 @@
     <xi:include href="overview.xml"/>
     <xi:include href="xml/getting_started.xml"/>
     <xi:include href="building.sgml" />
-    <xi:include href="compiling.sgml" />
+    <xi:include href="xml/compiling.sgml" />
     <xi:include href="running.sgml" />
     <xi:include href="x11.sgml" />
     <xi:include href="windows.sgml" />
diff --git a/gdk/gdk.c b/gdk/gdk.c
index f34da89..cdc4c4a 100644
--- a/gdk/gdk.c
+++ b/gdk/gdk.c
@@ -45,7 +45,19 @@
  * @Title: General
  *
  * This section describes the GDK initialization functions and miscellaneous
- * utility functions.
+ * utility functions, as well as deprecation facilities.
+ *
+ * The GDK and GTK+ headers annotate deprecated APIs in a way that produces
+ * compiler warnings if these deprecated APIs are used. The warnings
+ * can be turned off by defining the macro %GDK_DISABLE_DEPRECATION_WARNINGS
+ * before including the glib.h header.
+ *
+ * GDK and GTK+ also provide support for building applications against
+ * defined subsets of deprecated or new APIs. Define the macro
+ * %GDK_VERSION_MIN_REQUIRED to specify up to what version
+ * you want to receive warnings about deprecated APIs. Define the
+ * macro %GDK_VERSION_MAX_ALLOWED to specify the newest version
+ * whose API you want to use.
  */
 
 /**
@@ -75,6 +87,14 @@
  * Use this macro to guard code that is specific to the Quartz backend.
  */
 
+/**
+ * GDK_DISABLE_DEPRECATION_WARNINGS:
+ *
+ * A macro that should be defined before including the gdk.h header.
+ * If it is defined, no compiler warnings will be produced for uses
+ * of deprecated GDK APIs.
+ */
+
 typedef struct _GdkPredicate  GdkPredicate;
 
 struct _GdkPredicate
diff --git a/gdk/gdkversionmacros.h.in b/gdk/gdkversionmacros.h.in
index 1871455..cbb9265 100644
--- a/gdk/gdkversionmacros.h.in
+++ b/gdk/gdkversionmacros.h.in
@@ -30,6 +30,14 @@
 #define GDK_MINOR_VERSION (@GTK_MINOR_VERSION@)
 #define GDK_MICRO_VERSION (@GTK_MICRO_VERSION@)
 
+/**
+ * GDK_DISABLE_DEPRECATION_WARNINGS:
+ *
+ * A macro that should be defined before including the gdk.h header.
+ * If it is defined, no compiler warnings will be produced for uses
+ * of deprecated GDK and GTK+ APIs.
+ */
+
 #ifdef GDK_DISABLE_DEPRECATION_WARNINGS
 #define GDK_DEPRECATED
 #define GDK_DEPRECATED_FOR(f)