build: Add a LIBGDATA_DISABLE_DEPRECATED build flag

This only affects installed header files, to make it easier for clients to
ensure they're not using deprecated libgdata API. (If, for some reason,
G_GNUC_DEPRECATED_FOR doesn't cut it for them.)

It doesn't affect the compilation of libgdata.

5 files changed, 30 insertions, 1 deletions

diff --git a/HACKING b/HACKING
index 10507a55..9ab217e6 100644
--- a/HACKING
+++ b/HACKING
@@ -137,6 +137,27 @@ In general, use common sense. However, there are some specific cases where a sta
  - In general, try to keep API named similarly to the actual GData API constructs. In certain cases, however, it might make more sense to rename pieces
    of API to be less cryptic (e.g. "timezone" instead of "ctz": http://code.google.com/apis/calendar/docs/2.0/reference.html#Parameters).
 
+Deprecating public API
+======================
+
+As libgdata moves towards API stability, old API should be deprecated rather than broken or removed entirely. The following should be ensured when
+deprecating API:
+
+ - G_GNUC_DEPRECATED_FOR is added to the API in the public header file.
+
+ - A “Deprecated:” line is added to the gtk-doc comment for the API. This should mention what API replaces it, give a brief explanation of why the
+   API has been deprecated, and finish with “(Since: [version].)” to list the version the API was deprecated.
+
+ - “#ifndef LIBGDATA_DISABLE_DEPRECATED” should be wrapped around the API in the public header file.
+
+ - All references to the API/uses of the API in libgdata code (including demos and the test suite) should be ported to use the replacement API instead.
+   If this isn't possible, the deprecated function should be split into a static function which contains all the code, and the public symbol should
+   become a simple wrapper of this static function. This allows the static function to be used inside libgdata without causing deprecation warnings.
+
+ - Don't remove deprecated symbols from gdata.symbols.
+
+ - Don't forget to also deprecate related symbols, such as the getter/setter for a property (or vice-versa).
+
 Commit messages
 ===============
 
diff --git a/Makefile.am b/Makefile.am
index 42e2dc81..2a9ecebc 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -544,6 +544,7 @@ demos_scrapbook_scrapbook_CPPFLAGS = \
 	-I$(top_srcdir)/ \
 	-I$(top_srcdir)/gdata \
 	-DG_LOG_DOMAIN=\"scrapbook\" \
+	-DLIBGDATA_DISABLE_DEPRECATED \
 	$(DISABLE_DEPRECATED) \
 	$(AM_CPPFLAGS) \
 	$(NULL)
diff --git a/README b/README
index 6e3bfac5..2ef0388d 100644
--- a/README
+++ b/README
@@ -33,6 +33,12 @@ values, libgdata will give debug output (at various levels):
  3: Output debug messages and full network traffic logs
 If LIBGDATA_DEBUG is unset, no debug output will be produced.
 
+Deprecation guards
+==================
+
+If LIBGDATA_DISABLE_DEPRECATED is defined when compiling against libgdata, all
+deprecated API will be removed from included headers.
+
 Licensing
 =========
 
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index cbb8fa1f..ecfa9a52 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -25,7 +25,7 @@ SCANGOBJ_OPTIONS=
 
 # Extra options to supply to gtkdoc-scan.
 # e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED" 
-SCAN_OPTIONS=--rebuild-types
+SCAN_OPTIONS=--rebuild-types --deprecated-guards="LIBGDATA_DISABLE_DEPRECATED"
 
 # Extra options to supply to gtkdoc-mkdb.
 # e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml
diff --git a/gdata/tests/Makefile.am b/gdata/tests/Makefile.am
index 9e052fec..3c40451c 100644
--- a/gdata/tests/Makefile.am
+++ b/gdata/tests/Makefile.am
@@ -6,6 +6,7 @@ INCLUDES = \
 	$(GDK_PIXBUF_CFLAGS)				\
 	-DTEST_FILE_DIR="\"$(top_srcdir)/gdata/tests/\""\
 	-DG_LOG_DOMAIN=\"libgdata\"			\
+	-DLIBGDATA_DISABLE_DEPRECATED			\
 	$(DISABLE_DEPRECATED)				\
 	$(WARN_CFLAGS)					\
 	$(GDATA_CFLAGS)