[gtk+] docs: Move documentation to inline comments: general

[Javier Jardón <jjardon src gnome org>]

commit 1268c17983165cee4d94c53dc71ae7889bedc15f
Author: Javier Jardón <jjardon gnome org>
Date:   Mon Nov 15 04:58:21 2010 +0100

    docs: Move documentation to inline comments: general

 docs/reference/gdk/tmpl/.gitignore   |    1 +
 docs/reference/gdk/tmpl/general.sgml |  366 ----------------------------------
 gdk/gdk.c                            |   68 +++++--
 gdk/gdkmain.h                        |   37 ++++
 gdk/gdktypes.h                       |   15 +-
 gdk/gdkwindow.c                      |   17 +-
 6 files changed, 108 insertions(+), 396 deletions(-)
---
diff --git a/docs/reference/gdk/tmpl/.gitignore b/docs/reference/gdk/tmpl/.gitignore
index ef29778..5b8a121 100644
--- a/docs/reference/gdk/tmpl/.gitignore
+++ b/docs/reference/gdk/tmpl/.gitignore
@@ -6,6 +6,7 @@ gdkdisplay.sgml
 gdkdisplaymanager.sgml
 gdkscreen.sgml
 gdktesting.sgml
+general.sgml
 keys.sgml
 pixbufs.sgml
 regions.sgml
diff --git a/gdk/gdk.c b/gdk/gdk.c
index ba6582d..8c701ff 100644
--- a/gdk/gdk.c
+++ b/gdk/gdk.c
@@ -38,6 +38,17 @@
 #include <string.h>
 #include <stdlib.h>
 
+
+/**
+ * SECTION:general
+ * @Short_description: Library initialization and miscellaneous functions
+ * @Title: General
+ *
+ * This section describes the GDK initialization functions and miscellaneous
+ * utility functions.
+ */
+
+
 typedef struct _GdkPredicate  GdkPredicate;
 
 struct _GdkPredicate
@@ -338,25 +349,19 @@ gdk_display_open_default_libgtk_only (void)
 
 /**
  * gdk_init_check:
- * @argc: (inout):
- * @argv: (array length=argc) (inout):
+ * @argc: (inout): the number of command line arguments.
+ * @argv: (array length=argc) (inout): the array of command line arguments.
  *
- *   Initialize the library for use.
+ * Initializes the GDK library and connects to the X server, returning %TRUE on
+ * success.
  *
- * Arguments:
- *   "argc" is the number of arguments.
- *   "argv" is an array of strings.
- *
- * Results:
- *   "argc" and "argv" are modified to reflect any arguments
- *   which were not handled. (Such arguments should either
- *   be handled by the application or dismissed). If initialization
- *   fails, returns FALSE, otherwise TRUE.
+ * Any arguments used by GDK are removed from the array and @argc and @argv are
+ * updated accordingly.
  *
- * Side effects:
- *   The library is initialized.
+ * GTK+ initializes GDK in gtk_init() and so this function is not usually needed
+ * by GTK+ applications.
  *
- *--------------------------------------------------------------
+ * Returns: %TRUE if initialization succeeded.
  */
 gboolean
 gdk_init_check (int    *argc,
@@ -370,8 +375,18 @@ gdk_init_check (int    *argc,
 
 /**
  * gdk_init:
- * @argc: (inout):
- * @argv: (array length=argc) (inout):
+ * @argc: (inout): the number of command line arguments.
+ * @argv: (array length=argc) (inout): the array of command line arguments.
+ *
+ * Initializes the GDK library and connects to the X server.
+ * If initialization fails, a warning message is output and the application
+ * terminates with a call to <literal>exit(1)</literal>.
+ *
+ * Any arguments used by GDK are removed from the array and @argc and @argv are
+ * updated accordingly.
+ *
+ * GTK+ initializes GDK in gtk_init() and so this function is not usually needed
+ * by GTK+ applications.
  */
 void
 gdk_init (int *argc, char ***argv)
@@ -772,13 +787,30 @@ gdk_threads_add_timeout_seconds (guint       interval,
                                                interval, function, data, NULL);
 }
 
-
+/**
+ * gdk_get_program_class:
+ *
+ * Gets the program class. Unless the program class has explicitly
+ * been set with gdk_set_program_class() or with the <option>--class</option>
+ * commandline option, the default value is the program name (determined
+ * with g_get_prgname()) with the first character converted to uppercase.
+ *
+ * Returns: the program class.
+ */
 G_CONST_RETURN char *
 gdk_get_program_class (void)
 {
   return gdk_progclass;
 }
 
+/**
+ * gdk_set_program_class:
+ * @program_class: a string.
+ *
+ * Sets the program class. The X11 backend uses the program class to set
+ * the class name part of the <literal>WM_CLASS</literal> property on
+ * toplevel windows; see the ICCCM.
+ */
 void
 gdk_set_program_class (const char *program_class)
 {
diff --git a/gdk/gdkmain.h b/gdk/gdkmain.h
index f2ceaaa..75ffb4e 100644
--- a/gdk/gdkmain.h
+++ b/gdk/gdkmain.h
@@ -50,6 +50,27 @@ gboolean              gdk_init_check                      (gint           *argc,
 void                  gdk_add_option_entries_libgtk_only  (GOptionGroup   *group);
 void                  gdk_pre_parse_libgtk_only           (void);
 
+/**
+ * gdk_set_locale:
+ *
+ * Initializes the support for internationalization by calling the <function>setlocale()</function>
+ * system call. This function is called by gtk_set_locale() and so GTK+
+ * applications should use that instead.
+ *
+ * The locale to use is determined by the <envar>LANG</envar> environment variable,
+ * so to run an application in a certain locale you can do something like this:
+ * <informalexample>
+ * <programlisting>
+ *   export LANG="fr"
+ *   ... run application ...
+ * </programlisting>
+ * </informalexample>
+ *
+ * If the locale is not supported by X then it is reset to the standard "C"
+ * locale.
+ *
+ * Returns: the resulting locale.
+ */
 gchar*                gdk_set_locale                      (void);
 void                  gdk_enable_multidevice              (void);
 
@@ -68,6 +89,15 @@ void                           gdk_error_trap_pop_ignored (void);
 
 
 G_CONST_RETURN gchar *gdk_get_display_arg_name (void);
+
+/**
+ * gdk_get_display:
+ *
+ * Gets the name of the display, which usually comes from the <envar>DISPLAY</envar>
+ * environment variable or the <option>--display</option> command line option.
+ *
+ * Returns: the name of the display.
+ */
 gchar*	              gdk_get_display          (void);
 
 #ifndef GDK_MULTIDEVICE_SAFE
@@ -102,6 +132,13 @@ void gdk_beep (void);
 
 #endif /* GDK_MULTIHEAD_SAFE */
 
+/**
+ * gdk_flush:
+ *
+ * Flushes the X output buffer and waits until all requests have been processed
+ * by the server. This is rarely needed by applications. It's main use is for
+ * trapping X errors with gdk_error_trap_push() and gdk_error_trap_pop().
+ */
 void gdk_flush (void);
 
 G_END_DECLS
diff --git a/gdk/gdktypes.h b/gdk/gdktypes.h
index 53937d8..44efa3f 100644
--- a/gdk/gdktypes.h
+++ b/gdk/gdktypes.h
@@ -196,9 +196,18 @@ typedef enum
   GDK_ERROR_MEM	  = -4
 } GdkStatus;
 
-/* We define specific numeric values for these constants,
- * since old application code may depend on them matching the X values
- * We don't actually depend on the matchup ourselves.
+/**
+ * GdkGrabStatus:
+ * @GDK_GRAB_SUCCESS: the resource was successfully grabbed.
+ * @GDK_GRAB_ALREADY_GRABBED: the resource is actively grabbed by another client.
+ * @GDK_GRAB_INVALID_TIME: the resource was grabbed more recently than the
+ *  specified time.
+ * @GDK_GRAB_NOT_VIEWABLE: the grab window or the @confine_to window are not
+ *  viewable.
+ * @GDK_GRAB_FROZEN: the resource is frozen by an active grab of another client.
+ *
+ * Returned by gdk_pointer_grab() and gdk_keyboard_grab() to indicate
+ * success or the reason for the failure of the grab attempt.
  */
 typedef enum
 {
diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c
index d186b4d..c248598 100644
--- a/gdk/gdkwindow.c
+++ b/gdk/gdkwindow.c
@@ -8864,8 +8864,7 @@ _gdk_display_set_window_under_pointer (GdkDisplay *display,
  * Pointer grabs are used for operations which need complete control over mouse
  * events, even if the mouse leaves the application.
  * For example in GTK+ it is used for Drag and Drop, for dragging the handle in
- * the #GtkHPaned and #GtkVPaned widgets, and for resizing columns in #GtkCList
- * widgets.
+ * the #GtkHPaned and #GtkVPaned widgets.
  *
  * Note that if the event mask of an X window has selected both button press and
  * button release events, then a button press event will cause an automatic
@@ -8982,13 +8981,13 @@ gdk_pointer_grab (GdkWindow *	  window,
  * gdk_keyboard_grab:
  * @window: the #GdkWindow which will own the grab (the grab window).
  * @owner_events: if %FALSE then all keyboard events are reported with respect to
- *                @window. If %TRUE then keyboard events for this application are
- *                reported as normal, but keyboard events outside this application
- *                are reported with respect to @window. Both key press and key
- *                release events are always reported, independant of the event mask
- *                set by the application.
- * @time: a timestamp from a #GdkEvent, or %GDK_CURRENT_TIME if no timestamp is
-available.
+ *   @window. If %TRUE then keyboard events for this application are
+ *   reported as normal, but keyboard events outside this application
+ *   are reported with respect to @window. Both key press and key
+ *   release events are always reported, independant of the event mask
+ *   set by the application.
+ * @time_: a timestamp from a #GdkEvent, or %GDK_CURRENT_TIME if no timestamp is
+ *   available.
  *
  * Grabs the keyboard so that all events are passed to this
  * application until the keyboard is ungrabbed with gdk_keyboard_ungrab().