[libgdata] build: Add a LIBGDATA_DISABLE_DEPRECATED build flag

[Philip Withnall <pwithnall src gnome org>]

commit d8904f6c5b0e830df10157906ebfe7c612a18468
Author: Philip Withnall <philip tecnocode co uk>
Date:   Sun Oct 9 22:02:54 2011 +0100

    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.

 HACKING                    |   21 +++++++++++++++++++++
 Makefile.am                |    1 +
 README                     |    6 ++++++
 docs/reference/Makefile.am |    2 +-
 gdata/tests/Makefile.am    |    1 +
 5 files changed, 30 insertions(+), 1 deletions(-)
---
diff --git a/HACKING b/HACKING
index 10507a5..9ab217e 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 42e2dc8..2a9eceb 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 6e3bfac..2ef0388 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 cbb8fa1..ecfa9a5 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 9e052fe..3c40451 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)