[gedit/wip/utils-deprecations] Deprecate unused utils functions and macros (wip)

[Sébastien Wilmet <swilmet src gnome org>]

commit 570b0767790786a53df1612df59c66e0fa5a35da
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sat May 9 14:06:52 2015 +0200

    Deprecate unused utils functions and macros (wip)
    
    Maybe third-party plugins still use those deprecated functions. In that
    case the function can be copied into the plugin, or the plugin author
    can contact the gedit developers to undeprecate the function (if there
    is a good reason to do so).
    
    For macros a deprecated guard is needed for GTK-Doc, so add the
    GEDIT_DISABLE_DEPRECATED for the deprecated guard.

 docs/reference/Makefile.am |    2 +-
 gedit/gedit-utils.c        |   63 ++++++++++++++++++++++++++++++++------------
 gedit/gedit-utils.h        |   14 +++++++++-
 3 files changed, 60 insertions(+), 19 deletions(-)
---
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index 3e098c2..fc36f10 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -16,7 +16,7 @@ DOC_SOURCE_DIR = ../../gedit
 
 # 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="GEDIT_DISABLE_DEPRECATED"
 
 # Extra options to supply to gtkdoc-mkdb.
 MKDB_OPTIONS = --xml-mode --output-format=xml
diff --git a/gedit/gedit-utils.c b/gedit/gedit-utils.c
index 8ef9f75..2229dc0 100644
--- a/gedit/gedit-utils.c
+++ b/gedit/gedit-utils.c
@@ -232,8 +232,15 @@ gedit_warning (GtkWindow *parent, const gchar *format, ...)
        gtk_widget_show (dialog);
 }
 
-/*
+/**
+ * gedit_utils_escape_underscores:
+ * @text: some text.
+ * @length: the length.
+ *
  * Doubles underscore to avoid spurious menu accels.
+ *
+ * Returns: the text escaped.
+ * Deprecated: 3.18
  */
 gchar *
 gedit_utils_escape_underscores (const gchar *text,
@@ -393,16 +400,8 @@ gedit_utils_make_valid_utf8 (const char *name)
        return g_string_free (string, FALSE);
 }
 
-/**
- * gedit_utils_uri_get_dirname:
- * @uri: the URI.
- *
- * Note: this function replace home dir with ~
- *
- * Returns: the directory name.
- */
-gchar *
-gedit_utils_uri_get_dirname (const gchar *uri)
+static gchar *
+uri_get_dirname (const gchar *uri)
 {
        gchar *res;
        gchar *str;
@@ -428,6 +427,21 @@ gedit_utils_uri_get_dirname (const gchar *uri)
 }
 
 /**
+ * gedit_utils_uri_get_dirname:
+ * @uri: the URI.
+ *
+ * Note: this function replace home dir with ~.
+ *
+ * Returns: the directory name.
+ * Deprecated: 3.18
+ */
+gchar *
+gedit_utils_uri_get_dirname (const gchar *uri)
+{
+       return uri_get_dirname (uri);
+}
+
+/**
  * gedit_utils_location_get_dirname_for_display:
  * @location: the location
  *
@@ -470,11 +484,11 @@ gedit_utils_location_get_dirname_for_display (GFile *location)
 
                if (path == NULL)
                {
-                       dirname = gedit_utils_uri_get_dirname (uri);
+                       dirname = uri_get_dirname (uri);
                }
                else
                {
-                       dirname = gedit_utils_uri_get_dirname (path);
+                       dirname = uri_get_dirname (path);
                }
 
                if (dirname == NULL || strcmp (dirname, ".") == 0)
@@ -493,7 +507,7 @@ gedit_utils_location_get_dirname_for_display (GFile *location)
        else
        {
                /* fallback for local files or uris without mounts */
-               res = gedit_utils_uri_get_dirname (uri);
+               res = uri_get_dirname (uri);
        }
 
        g_free (uri);
@@ -948,6 +962,7 @@ get_ui_objects_with_translation_domain (const gchar  *filename,
  * the error message to display.
  *
  * Returns: %FALSE if an error occurs, %TRUE on success.
+ * Deprecated: 3.18
  */
 gboolean
 gedit_utils_get_ui_objects (const gchar  *filename,
@@ -987,6 +1002,7 @@ gedit_utils_get_ui_objects (const gchar  *filename,
  * the error message to display.
  *
  * Returns: %FALSE if an error occurs, %TRUE on success.
+ * Deprecated: 3.18
  */
 gboolean
 gedit_utils_get_ui_objects_with_translation_domain (const gchar  *filename,
@@ -1011,8 +1027,8 @@ gedit_utils_get_ui_objects_with_translation_domain (const gchar  *filename,
        return ret;
 }
 
-gchar *
-gedit_utils_make_canonical_uri_from_shell_arg (const gchar *str)
+static gchar *
+make_canonical_uri_from_shell_arg (const gchar *str)
 {
        GFile *gfile;
        gchar *uri;
@@ -1051,6 +1067,19 @@ gedit_utils_make_canonical_uri_from_shell_arg (const gchar *str)
 }
 
 /**
+ * gedit_utils_make_canonical_uri_from_shell_arg:
+ * @str: shell arg.
+ *
+ * Returns: canonical URI, or %NULL if @str is not a valid URI and/or filename.
+ * Deprecated: 3.18
+ */
+gchar *
+gedit_utils_make_canonical_uri_from_shell_arg (const gchar *str)
+{
+       return make_canonical_uri_from_shell_arg (str);
+}
+
+/**
  * gedit_utils_basename_for_display:
  * @location: location for which the basename should be displayed
  *
@@ -1163,7 +1192,7 @@ gedit_utils_drop_get_uris (GtkSelectionData *selection_data)
        {
                gchar *uri;
 
-               uri = gedit_utils_make_canonical_uri_from_shell_arg (uris[i]);
+               uri = make_canonical_uri_from_shell_arg (uris[i]);
 
                /* Silently ignore malformed URI/filename */
                if (uri != NULL)
diff --git a/gedit/gedit-utils.h b/gedit/gedit-utils.h
index c19e4f2..5032d1e 100644
--- a/gedit/gedit-utils.h
+++ b/gedit/gedit-utils.h
@@ -31,7 +31,15 @@ G_BEGIN_DECLS
 #define GBOOLEAN_TO_POINTER(i) (GINT_TO_POINTER ((i) ? 2 : 1))
 #define GPOINTER_TO_BOOLEAN(i) ((gboolean) ((GPOINTER_TO_INT(i) == 2) ? TRUE : FALSE))
 
+/**
+ * IS_VALID_BOOLEAN:
+ * @v: a gboolean.
+ *
+ * Deprecated: 3.18
+ */
+#ifndef GEDIT_DISABLE_DEPRECATED
 #define IS_VALID_BOOLEAN(v) (((v == TRUE) || (v == FALSE)) ? TRUE : FALSE)
+#endif
 
 enum { GEDIT_ALL_WORKSPACES = 0xffffffff };
 
@@ -48,6 +56,7 @@ void           gedit_utils_menu_position_under_tree_view
                                                         gboolean         *push_in,
                                                         gpointer          user_data);
 
+G_DEPRECATED
 gchar          *gedit_utils_escape_underscores         (const gchar      *text,
                                                         gssize            length);
 
@@ -72,6 +81,7 @@ void           gedit_warning                          (GtkWindow        *parent,
 gchar          *gedit_utils_make_valid_utf8            (const char       *name);
 
 /* Note that this function replace home dir with ~ */
+G_DEPRECATED
 gchar          *gedit_utils_uri_get_dirname            (const char       *uri);
 
 gchar          *gedit_utils_location_get_dirname_for_display
@@ -89,12 +99,14 @@ void                 gedit_utils_get_current_viewport       (GdkScreen        *screen,
 
 gboolean        gedit_utils_is_valid_location          (GFile            *location);
 
+G_DEPRECATED
 gboolean        gedit_utils_get_ui_objects             (const gchar      *filename,
                                                         gchar           **root_objects,
                                                         GtkWidget       **error_widget,
                                                         const gchar      *object_name,
                                                         ...) G_GNUC_NULL_TERMINATED;
 
+G_DEPRECATED
 gboolean         gedit_utils_get_ui_objects_with_translation_domain
                                                         (const gchar  *filename,
                                                          const gchar  *translation_domain,
@@ -103,7 +115,7 @@ gboolean         gedit_utils_get_ui_objects_with_translation_domain
                                                          const gchar  *object_name,
                                                          ...) G_GNUC_NULL_TERMINATED;
 
-/* Return NULL if str is not a valid URI and/or filename */
+G_DEPRECATED
 gchar          *gedit_utils_make_canonical_uri_from_shell_arg
                                                        (const gchar      *str);