[glib] Deprecate some rarely-used APIS

[Matthias Clasen <matthiasc src gnome org>]

commit 17bc9bf94f2a11ce553d784e55649b43f3ed0130
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Jun 23 22:32:35 2010 -0400

    Deprecate some rarely-used APIS
    
    GRelation and GCompletion are almost never used, and not very actively
    maintained. Mark them as deprecated to make this clear. Bug #551271.

 glib/gcompletion.c |   25 ++++++++++++++++++++++++-
 glib/gcompletion.h |    4 ++++
 glib/grel.c        |   35 ++++++++++++++++++++++++++++++++++-
 glib/grel.h        |    4 ++++
 4 files changed, 66 insertions(+), 2 deletions(-)
---
diff --git a/glib/gcompletion.c b/glib/gcompletion.c
index 904f850..2a1832a 100644
--- a/glib/gcompletion.c
+++ b/glib/gcompletion.c
@@ -32,7 +32,13 @@
 
 #include <string.h>
 
-#include "glib.h"
+#include "gstrfuncs.h"
+#include "gmessages.h"
+#include "gunicode.h"
+
+#undef G_DISABLE_DEPRECATED
+
+#include "gcompletion.h"
 #include "galias.h"
 
 /**
@@ -58,6 +64,9 @@
  * retrieves the item's string from the data structure. You can change
  * the way in which strings are compared by setting a different
  * #GCompletionStrncmpFunc in g_completion_set_compare().
+ *
+ * GCompletion has been marked as deprecated, since this API is rarely
+ * used and not very actively maintained.
  **/
 
 /**
@@ -132,6 +141,8 @@ g_completion_new (GCompletionFunc func)
  * @items: the list of items to add.
  *
  * Adds items to the #GCompletion.
+ *
+ * Deprecated: 2.26: Rarely used API
  **/
 void 
 g_completion_add_items (GCompletion* cmp,
@@ -168,6 +179,8 @@ g_completion_add_items (GCompletion* cmp,
  * @items: the items to remove.
  *
  * Removes items from a #GCompletion.
+ *
+ * Deprecated: 2.26: Rarely used API
  **/
 void 
 g_completion_remove_items (GCompletion* cmp,
@@ -197,6 +210,8 @@ g_completion_remove_items (GCompletion* cmp,
  * @cmp: the #GCompletion.
  *
  * Removes all items from the #GCompletion.
+ *
+ * Deprecated: 2.26: Rarely used API
  **/
 void 
 g_completion_clear_items (GCompletion* cmp)
@@ -276,6 +291,8 @@ completion_check_cache (GCompletion* cmp,
  * not be changed.
  *
  * Since: 2.4
+ *
+ * Deprecated: 2.26: Rarely used API
  **/
 GList*
 g_completion_complete_utf8 (GCompletion  *cmp,
@@ -320,6 +337,8 @@ g_completion_complete_utf8 (GCompletion  *cmp,
  *
  * Attempts to complete the string @prefix using the #GCompletion
  * target items.
+ *
+ * Deprecated: 2.26: Rarely used API
  **/
 GList* 
 g_completion_complete (GCompletion* cmp,
@@ -388,6 +407,8 @@ g_completion_complete (GCompletion* cmp,
  * @cmp: the #GCompletion.
  *
  * Frees all memory used by the #GCompletion.
+ *
+ * Deprecated: 2.26: Rarely used API
  **/
 void 
 g_completion_free (GCompletion* cmp)
@@ -405,6 +426,8 @@ g_completion_free (GCompletion* cmp)
  *
  * Sets the function to use for string comparisons. The default string
  * comparison function is strncmp().
+ *
+ * Deprecated: 2.26: Rarely used API
  **/
 void
 g_completion_set_compare(GCompletion *cmp,
diff --git a/glib/gcompletion.h b/glib/gcompletion.h
index 900883e..04c024f 100644
--- a/glib/gcompletion.h
+++ b/glib/gcompletion.h
@@ -56,6 +56,8 @@ struct _GCompletion
   GCompletionStrncmpFunc strncmp_func;
 };
 
+#ifndef G_DISABLE_DEPRECATED
+
 GCompletion* g_completion_new           (GCompletionFunc func);
 void         g_completion_add_items     (GCompletion*    cmp,
                                          GList*          items);
@@ -72,6 +74,8 @@ void         g_completion_set_compare   (GCompletion *cmp,
 				         GCompletionStrncmpFunc strncmp_func);
 void         g_completion_free          (GCompletion*    cmp);
 
+#endif
+
 G_END_DECLS
 
 #endif /* __G_COMPLETION_H__ */
diff --git a/glib/grel.c b/glib/grel.c
index 8cecd29..7609274 100644
--- a/glib/grel.c
+++ b/glib/grel.c
@@ -32,7 +32,14 @@
 #include <stdarg.h>
 #include <string.h>
 
-#include "glib.h"
+#include "ghash.h"
+#include "gmessages.h"
+#include "gtestutils.h"
+#include "gstring.h"
+
+#undef G_DISABLE_DEPRECATED
+
+#include "grel.h"
 #include "galias.h"
 
 /**
@@ -76,6 +83,10 @@
  * To destroy the #GRelation, use g_relation_destroy().
  *
  * To help debug #GRelation objects, use g_relation_print().
+ *
+ * GRelation has been marked as deprecated, since this API has never
+ * been fully implemented, is not very actively maintained and rarely
+ * used.
  **/
 
 typedef struct _GRealTuples        GRealTuples;
@@ -177,6 +188,8 @@ tuple_equal (gint fields)
  *
  * Creates a new #GRelation with the given number of fields. Note that
  * currently the number of fields must be 2.
+ *
+ * Deprecated: 2.26: Rarely used API
  **/
 GRelation*
 g_relation_new (gint fields)
@@ -213,6 +226,8 @@ g_relation_free_array (gpointer key, gpointer value, gpointer user_data)
  * Destroys the #GRelation, freeing all memory allocated. However, it
  * does not free memory allocated for the tuple data, so you should
  * free that first if appropriate.
+ *
+ * Deprecated: 2.26: Rarely used API
  **/
 void
 g_relation_destroy (GRelation *relation)
@@ -247,6 +262,8 @@ g_relation_destroy (GRelation *relation)
  *
  * Creates an index on the given field. Note that this must be called
  * before any records are added to the #GRelation.
+ *
+ * Deprecated: 2.26: Rarely used API
  **/
 void
 g_relation_index (GRelation   *relation,
@@ -269,6 +286,8 @@ g_relation_index (GRelation   *relation,
  *           or #gconstpointer.
  *
  * Inserts a record into a #GRelation.
+ *
+ * Deprecated: 2.26: Rarely used API
  **/
 void
 g_relation_insert (GRelation   *relation,
@@ -359,6 +378,8 @@ g_relation_delete_tuple (gpointer tuple_key,
  *
  * Deletes any records from a #GRelation that have the given key value
  * in the given field.
+ *
+ * Deprecated: 2.26: Rarely used API
  **/
 gint
 g_relation_delete  (GRelation     *relation,
@@ -422,6 +443,8 @@ g_relation_select_tuple (gpointer tuple_key,
  * Returns all of the tuples which have the given key in the given
  * field. Use g_tuples_index() to access the returned records. The
  * returned records should be freed with g_tuples_destroy().
+ *
+ * Deprecated: 2.26: Rarely used API
  **/
 GTuples*
 g_relation_select (GRelation     *relation,
@@ -466,6 +489,8 @@ g_relation_select (GRelation     *relation,
  *
  * Returns the number of tuples in a #GRelation that have the given
  * value in the given field.
+ *
+ * Deprecated: 2.26: Rarely used API
  **/
 gint
 g_relation_count (GRelation     *relation,
@@ -499,6 +524,8 @@ g_relation_count (GRelation     *relation,
  * Returns %TRUE if a record with the given values exists in a
  * #GRelation. Note that the values are compared directly, so that, for
  * example, two copies of the same string will not match.
+ *
+ * Deprecated: 2.26: Rarely used API
  **/
 gboolean
 g_relation_exists (GRelation   *relation, ...)
@@ -530,6 +557,8 @@ g_relation_exists (GRelation   *relation, ...)
  * should always be called after g_relation_select() when you are
  * finished with the records. The records are not removed from the
  * #GRelation.
+ *
+ * Deprecated: 2.26: Rarely used API
  **/
 void
 g_tuples_destroy (GTuples *tuples0)
@@ -553,6 +582,8 @@ g_tuples_destroy (GTuples *tuples0)
  * Gets a field from the records returned by g_relation_select(). It
  * returns the given field of the record at the given index. The
  * returned value should not be changed.
+ *
+ * Deprecated: 2.26: Rarely used API
  **/
 gpointer
 g_tuples_index (GTuples     *tuples0,
@@ -616,6 +647,8 @@ g_relation_print_index (gpointer tuple_key,
  *
  * Outputs information about all records in a #GRelation, as well as
  * the indexes. It is for debugging.
+ *
+ * Deprecated: 2.26: Rarely used API
  **/
 void
 g_relation_print (GRelation *relation)
diff --git a/glib/grel.h b/glib/grel.h
index e7c9291..5cb8d09 100644
--- a/glib/grel.h
+++ b/glib/grel.h
@@ -66,6 +66,8 @@ struct _GTuples
  * g_relation_count() counts ...
  */
 
+#ifndef G_DISABLE_DEPRECATED
+
 GRelation* g_relation_new     (gint         fields);
 void       g_relation_destroy (GRelation   *relation);
 void       g_relation_index   (GRelation   *relation,
@@ -92,6 +94,8 @@ gpointer   g_tuples_index     (GTuples     *tuples,
                                gint         index_,
                                gint         field);
 
+#endif
+
 G_END_DECLS
 
 #endif /* __G_REL_H__ */