From f6d8c8a717851c282c90b168492e9c5ee23cfc80 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Mon, 27 Feb 2012 07:56:29 -0500 Subject: [PATCH] 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 97565187b9..9d63807a13 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 + +GDK_VERSION_3_0 +GDK_VERSION_3_2 +GDK_VERSION_3_4 +GDK_VERSION_MIN_REQUIRED +GDK_VERSION_MAX_ALLOWED +GDK_DISABLE_DEPRECATION_WARNINGS + 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 - + diff --git a/docs/reference/gtk/Makefile.am b/docs/reference/gtk/Makefile.am index 5099c337a3..b0083fc670 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 f4021c6ede..03206d9206 100644 --- 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 -DGDK_DISABLE_DEPRECATION_WARNINGS + +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. + + 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 c435070341..f3e744a2ca 100644 --- a/docs/reference/gtk/gtk-docs.sgml +++ b/docs/reference/gtk/gtk-docs.sgml @@ -23,7 +23,7 @@ - + diff --git a/gdk/gdk.c b/gdk/gdk.c index f34da89282..cdc4c4a8bc 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 1871455e0c..cbb92653ef 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)