Add some documentation around deprecations

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>
+

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				\

docs/reference/gtk/compiling.sgml

@@ -51,10 +51,18 @@ 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

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" />

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

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)