Add some documentation around deprecations

diff --git a/docs/reference/gdk/gdk3-sections.txt b/docs/reference/gdk/gdk3-sections.txt
index 97565187b9082caeac9eeeeead193c30a2cc725e..9d63807a132bb81024f38d1fe9830cc1e2aa1dbe 100644 (file)
--- 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 5099c337a355f3c8f726a56d53860f8671065006..b0083fc67000faacb0c05a185192b8b4190c979f 100644 (file)
--- 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 f4021c6ede4c17277dff15d857463b26c433f9c4..03206d92067197cbd8a57ad5cf6bfe4578f685ab 100644 (file)
--- a/docs/reference/gtk/compiling.sgml
+++ b/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

diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index c435070341a31eeb6a737134ebd39439b8dcc625..f3e744a2cad68a88688e6b630704310d798e1aea 100644 (file)
--- 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 f34da89282247467fbe8e67daa74808b6ef75868..cdc4c4a8bc25394d39f39afa593f9957dfeabc7e 100644 (file)
--- 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 1871455e0c50cd0836bc41f8b5f0d504dcd85606..cbb92653efe554d584a27fdbbd63753b43115b1e 100644 (file)
--- 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)