[gedit/wip/gcode: 5/6] gcode: do not duplicate comments that are already present in gedit

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

commit 8af8055c1233d70f972fdc1af9999c1385e15d56
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sun May 3 12:24:22 2015 +0200

    gcode: do not duplicate comments that are already present in gedit
    
    The documentation should be in gedit, not in gcode, because plugin
    authors will look at the gedit documentation. For now gcode is
    completely internal to gedit.

 gcode/gcode-debug.c |   42 +-----------------
 gcode/gcode-debug.h |    9 +---
 gcode/gcode-utils.c |  115 +++++----------------------------------------------
 gcode/gcode-utils.h |    4 --
 4 files changed, 16 insertions(+), 154 deletions(-)
---
diff --git a/gcode/gcode-debug.c b/gcode/gcode-debug.c
index 53e5566..eece305 100644
--- a/gcode/gcode-debug.c
+++ b/gcode/gcode-debug.c
@@ -34,22 +34,7 @@ static GcodeDebugSection enabled_sections = GCODE_NO_DEBUG;
 
 #define DEBUG_IS_ENABLED(section) (enabled_sections & (section))
 
-/**
- * gcode_debug_init:
- *
- * Initializes the debugging subsystem of gcode.
- *
- * The function checks for the existence of certain environment variables to
- * determine whether to enable output for a debug section. To enable output
- * for a specific debug section, set an environment variable of the same name;
- * e.g. to enable output for the %GCODE_DEBUG_PLUGINS section, set a
- * <code>GCODE_DEBUG_PLUGINS</code> environment variable. To enable output
- * for all debug sections, set the <code>GCODE_DEBUG</code> environment
- * variable.
- *
- * This function must be called before any of the other debug functions are
- * called. It must only be called once.
- */
+/* See gedit_debug_init(). */
 void
 gcode_debug_init (void)
 {
@@ -75,16 +60,7 @@ out:
 #endif
 }
 
-/**
- * gcode_debug:
- * @section: debug section.
- * @file: file name.
- * @line: line number.
- * @function: name of the function that is calling gcode_debug().
- *
- * If @section is enabled, then logs the trace information @file, @line, and
- * @function.
- */
+/* See gedit_debug(). */
 void
 gcode_debug (GcodeDebugSection  section,
             const gchar       *file,
@@ -94,19 +70,7 @@ gcode_debug (GcodeDebugSection  section,
        gcode_debug_message (section, file, line, function, "%s", "");
 }
 
-/**
- * gcode_debug_message:
- * @section: debug section.
- * @file: file name.
- * @line: line number.
- * @function: name of the function that is calling gcode_debug_message().
- * @format: A g_vprintf() format string.
- * @...: The format string arguments.
- *
- * If @section is enabled, then logs the trace information @file, @line, and
- * @function along with the message obtained by formatting @format with the
- * given format string arguments.
- */
+/* See gedit_debug_message(). */
 void
 gcode_debug_message (GcodeDebugSection  section,
                     const gchar       *file,
diff --git a/gcode/gcode-debug.h b/gcode/gcode-debug.h
index 6211089..f9ccd4d 100644
--- a/gcode/gcode-debug.h
+++ b/gcode/gcode-debug.h
@@ -28,13 +28,7 @@
 /**
  * GcodeDebugSection:
  *
- * Enumeration of debug sections.
- *
- * Debugging output for a section is enabled by setting an environment variable
- * of the same name. For example, setting the <code>GCODE_DEBUG_PLUGINS</code>
- * environment variable enables all debugging output for the %GCODE_DEBUG_PLUGINS
- * section. Setting the special environment variable <code>GCODE_DEBUG</code>
- * enables output for all sections.
+ * See GeditDebugSection. Replace "GEDIT" by "GCODE".
  */
 typedef enum {
        GCODE_NO_DEBUG       = 0,
@@ -57,4 +51,5 @@ void gcode_debug_message (GcodeDebugSection  section,
                          const gchar       *format, ...) G_GNUC_PRINTF(5, 6);
 
 #endif /* __GCODE_DEBUG_H__ */
+
 /* ex:set ts=8 noet: */
diff --git a/gcode/gcode-utils.c b/gcode/gcode-utils.c
index 0102240..2a7e5d3 100644
--- a/gcode/gcode-utils.c
+++ b/gcode/gcode-utils.c
@@ -128,15 +128,7 @@ gcode_utils_menu_position_under_tree_view (GtkMenu  *menu,
        }
 }
 
-/**
- * gcode_utils_set_atk_name_description:
- * @widget: The Gtk widget for which name/description to be set
- * @name: Atk name string
- * @description: Atk description string
- *
- * This function sets up name and description
- * for a specified gtk widget.
- */
+/* See gedit_utils_set_atk_name_description(). */
 void
 gcode_utils_set_atk_name_description (GtkWidget   *widget,
                                      const gchar *name,
@@ -156,15 +148,7 @@ gcode_utils_set_atk_name_description (GtkWidget   *widget,
                atk_object_set_description (aobj, description);
 }
 
-/**
- * gcode_set_atk_relation:
- * @obj1: specified widget.
- * @obj2: specified widget.
- * @rel_type: the type of relation to set up.
- *
- * This function establishes atk relation
- * between 2 specified widgets.
- */
+/* See gedit_utils_set_atk_relation(). */
 void
 gcode_utils_set_atk_relation (GtkWidget       *obj1,
                              GtkWidget       *obj2,
@@ -190,9 +174,7 @@ gcode_utils_set_atk_relation (GtkWidget       *obj1,
        g_object_unref (G_OBJECT (relation));
 }
 
-/*
- * Doubles underscore to avoid spurious menu accels.
- */
+/* See gedit_utils_escape_underscores(). */
 gchar *
 gcode_utils_escape_underscores (const gchar *text,
                                gssize       length)
@@ -351,14 +333,7 @@ gcode_utils_make_valid_utf8 (const char *name)
        return g_string_free (string, FALSE);
 }
 
-/**
- * gcode_utils_uri_get_dirname:
- * @uri: the URI.
- *
- * Note: this function replace home dir with ~
- *
- * Returns: the directory name.
- */
+/* See gedit_utils_uri_get_dirname(). */
 gchar *
 gcode_utils_uri_get_dirname (const gchar *uri)
 {
@@ -385,17 +360,7 @@ gcode_utils_uri_get_dirname (const gchar *uri)
        return res;
 }
 
-/**
- * gcode_utils_location_get_dirname_for_display:
- * @location: the location
- *
- * Returns a string suitable to be displayed in the UI indicating
- * the name of the directory where the file is located.
- * For remote files it may also contain the hostname etc.
- * For local files it tries to replace the home dir with ~.
- *
- * Returns: (transfer full): a string to display the dirname
- */
+/* See gedit_utils_location_get_dirname_for_display(). */
 gchar *
 gcode_utils_location_get_dirname_for_display (GFile *location)
 {
@@ -506,15 +471,7 @@ gcode_utils_replace_home_dir_with_tilde (const gchar *uri)
 
 /* the following two functions are courtesy of galeon */
 
-/**
- * gcode_utils_get_current_workspace:
- * @screen: a #GdkScreen
- *
- * Get the currently visible workspace for the #GdkScreen.
- *
- * If the X11 window property isn't found, 0 (the first workspace)
- * is returned.
- */
+/* See gedit_utils_get_current_workspace(). */
 guint
 gcode_utils_get_current_workspace (GdkScreen *screen)
 {
@@ -561,18 +518,7 @@ gcode_utils_get_current_workspace (GdkScreen *screen)
 #endif
 }
 
-/**
- * gcode_utils_get_window_workspace:
- * @gtkwindow: a #GtkWindow.
- *
- * Get the workspace the window is on.
- *
- * This function gets the workspace that the #GtkWindow is visible on,
- * it returns GCODE_ALL_WORKSPACES if the window is sticky, or if
- * the window manager doesn't support this function.
- *
- * Returns: the workspace the window is on.
- */
+/* See gedit_utils_get_window_workspace(). */
 guint
 gcode_utils_get_window_workspace (GtkWindow *gtkwindow)
 {
@@ -619,16 +565,7 @@ gcode_utils_get_window_workspace (GtkWindow *gtkwindow)
 #endif
 }
 
-/**
- * gcode_utils_get_current_viewport:
- * @screen: a #GdkScreen
- * @x: (out): x-axis point.
- * @y: (out): y-axis point.
- *
- * Get the currently visible viewport origin for the #GdkScreen.
- *
- * If the X11 window property isn't found, (0, 0) is returned.
- */
+/* See gedit_utils_get_current_viewport(). */
 void
 gcode_utils_get_current_viewport (GdkScreen    *screen,
                                  gint         *x,
@@ -802,12 +739,7 @@ gcode_utils_make_canonical_uri_from_shell_arg (const gchar *str)
        return NULL;
 }
 
-/**
- * gcode_utils_basename_for_display:
- * @location: location for which the basename should be displayed
- *
- * Returns: (transfer full): the basename of a file suitable for display to users.
- */
+/* See gedit_utils_basename_for_display(). */
 gchar *
 gcode_utils_basename_for_display (GFile *location)
 {
@@ -890,16 +822,7 @@ gcode_utils_basename_for_display (GFile *location)
        return name;
 }
 
-/**
- * gcode_utils_drop_get_uris:
- * @selection_data: the #GtkSelectionData from drag_data_received
- *
- * Create a list of valid uri's from a uri-list drop.
- *
- * Returns: (transfer full): a string array which will hold the uris or
- *           %NULL if there were no valid uris. g_strfreev should be used when
- *           the string array is no longer used
- */
+/* See gedit_utils_drop_get_uris(). */
 gchar **
 gcode_utils_drop_get_uris (GtkSelectionData *selection_data)
 {
@@ -940,23 +863,7 @@ null_ptr (gchar **ptr)
                *ptr = NULL;
 }
 
-/**
- * gcode_utils_decode_uri:
- * @uri: the uri to decode
- * @scheme: (out) (allow-none): return value pointer for the uri's
- * scheme (e.g. http, sftp, ...), or %NULL
- * @user: (out) (allow-none): return value pointer for the uri user info, or %NULL
- * @port: (out) (allow-none): return value pointer for the uri port, or %NULL
- * @host: (out) (allow-none): return value pointer for the uri host, or %NULL
- * @path: (out) (allow-none): return value pointer for the uri path, or %NULL
- *
- * Parse and break an uri apart in its individual components like the uri
- * scheme, user info, port, host and path. The return value pointer can be
- * %NULL to ignore certain parts of the uri. If the function returns %TRUE, then
- * all return value pointers should be freed using g_free
- *
- * Return value: %TRUE if the uri could be properly decoded, %FALSE otherwise.
- */
+/* See gedit_utils_decode_uri(). */
 gboolean
 gcode_utils_decode_uri (const gchar  *uri,
                        gchar       **scheme,
diff --git a/gcode/gcode-utils.h b/gcode/gcode-utils.h
index 59c686d..435d306 100644
--- a/gcode/gcode-utils.h
+++ b/gcode/gcode-utils.h
@@ -67,7 +67,6 @@ void           gcode_utils_set_atk_relation           (GtkWidget        *obj1,
 
 gchar          *gcode_utils_make_valid_utf8            (const char       *name);
 
-/* Note that this function replace home dir with ~ */
 gchar          *gcode_utils_uri_get_dirname            (const char       *uri);
 
 gchar          *gcode_utils_location_get_dirname_for_display
@@ -85,7 +84,6 @@ void           gcode_utils_get_current_viewport       (GdkScreen        *screen,
 
 gboolean        gcode_utils_is_valid_location          (GFile            *location);
 
-/* Return NULL if str is not a valid URI and/or filename */
 gchar          *gcode_utils_make_canonical_uri_from_shell_arg
                                                        (const gchar      *str);
 
@@ -97,8 +95,6 @@ gboolean       gcode_utils_decode_uri                 (const gchar      *uri,
                                                         gchar           **host,
                                                         gchar           **path);
 
-
-/* Turns data from a drop into a list of well formatted uris */
 gchar          **gcode_utils_drop_get_uris             (GtkSelectionData *selection_data);
 
 GtkSourceCompressionType