[glib] Minor documentation additions and corrections

[Matthias Clasen <matthiasc src gnome org>]

commit ab18d71e6f7a281687dd39b2616ae3a41fdaaf29
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat May 31 09:04:11 2014 -0400

    Minor documentation additions and corrections
    
    Going for 100%.

 glib/deprecated/gthread-deprecated.c |    2 +
 glib/docs.c                          |    8 +++++-
 glib/gconvert.h                      |    7 ++---
 glib/giochannel.c                    |    7 +----
 glib/gmessages.c                     |    7 +++++
 glib/gpoll.h                         |    8 ++++++
 glib/gregex.h                        |   13 +++++++--
 glib/gscanner.c                      |    8 ++++++
 glib/gvariant-parser.c               |    2 +
 glib/gversion.c                      |   47 ++++++++++++++++++++++++++++++++++
 gobject/gvalue.c                     |   11 ++++---
 11 files changed, 101 insertions(+), 19 deletions(-)
---
diff --git a/glib/deprecated/gthread-deprecated.c b/glib/deprecated/gthread-deprecated.c
index 497657f..47a1fbb 100644
--- a/glib/deprecated/gthread-deprecated.c
+++ b/glib/deprecated/gthread-deprecated.c
@@ -54,6 +54,8 @@
  * @G_THREAD_PRIORITY_HIGH: a priority higher than normal
  * @G_THREAD_PRIORITY_URGENT: the highest priority
  *
+ * Thread priorities.
+ *
  * Deprecated:2.32: Thread priorities no longer have any effect.
  */
 
diff --git a/glib/docs.c b/glib/docs.c
index 025491b..5a20cf2 100644
--- a/glib/docs.c
+++ b/glib/docs.c
@@ -1702,7 +1702,7 @@
  * arrays or arrays on the stack.
  */
  
-/ * Miscellaneous Macros {{{1 */
+/* Miscellaneous Macros {{{1 */
 
 /**
  * SECTION:macros_misc
@@ -2294,6 +2294,12 @@
  * Since: 2.4
  */
 
+/**
+ * G_HAVE_GNUC_VISIBILITY:
+ *
+ * Defined to 1 if gcc-style visibility handling is supported.
+ */
+
 /* Windows Compatibility Functions {{{1 */
 
 /**
diff --git a/glib/gconvert.h b/glib/gconvert.h
index ee7ece7..1b2369d 100644
--- a/glib/gconvert.h
+++ b/glib/gconvert.h
@@ -69,11 +69,10 @@ GLIB_AVAILABLE_IN_ALL
 GQuark g_convert_error_quark (void);
 
 /**
- * GIconv:
+ * GIConv:
  *
- * The <structname>GIConv</structname> struct wraps an
- * iconv() conversion descriptor. It contains private data
- * and should only be accessed using the following functions.
+ * The GIConv struct wraps an iconv() conversion descriptor. It contains
+ * private data and should only be accessed using the following functions.
  */
 typedef struct _GIConv *GIConv;
 
diff --git a/glib/giochannel.c b/glib/giochannel.c
index f13f6c5..447bb4f 100644
--- a/glib/giochannel.c
+++ b/glib/giochannel.c
@@ -942,7 +942,7 @@ g_io_channel_get_line_term (GIOChannel *channel,
  *     This flag cannot be changed.
  * @G_IO_FLAG_IS_WRITABLE: indicates that the io channel is writable.
  *     This flag cannot be changed.
- * G_IO_FLAG_IS_WRITEABLE: a misspelled version of @G_IO_FLAG_IS_WRITABLE
+ * @G_IO_FLAG_IS_WRITEABLE: a misspelled version of @G_IO_FLAG_IS_WRITABLE
  *     that existed before the spelling was fixed in GLib 2.30. It is kept
  *     here for compatibility reasons. Deprecated since 2.30
  * @G_IO_FLAG_IS_SEEKABLE: indicates that the io channel is seekable,
@@ -2530,11 +2530,6 @@ g_io_channel_write_unichar (GIOChannel  *channel,
 }
 
 /**
- * g_io_channel_error_quark:
- *
- * Returns: the quark used as %G_IO_CHANNEL_ERROR
- **/
-/**
  * G_IO_CHANNEL_ERROR:
  *
  * Error domain for #GIOChannel operations. Errors in this domain will
diff --git a/glib/gmessages.c b/glib/gmessages.c
index 7288fc4..8ea7295 100644
--- a/glib/gmessages.c
+++ b/glib/gmessages.c
@@ -155,6 +155,13 @@
  */
 
 /**
+ * G_LOG_LEVEL_USER_SHIFT:
+ *
+ * Log levels below 1<<G_LOG_LEVEL_USER_SHIFT are used by GLib.
+ * Higher bits can be used for user-defined log levels.
+ */
+
+/**
  * g_message:
  * @...: format string, followed by parameters to insert
  *     into the format string (as with printf())
diff --git a/glib/gpoll.h b/glib/gpoll.h
index d6204af..f28e3c5 100644
--- a/glib/gpoll.h
+++ b/glib/gpoll.h
@@ -90,7 +90,9 @@ typedef gint    (*GPollFunc)    (GPollFD *ufds,
 struct _GPollFD
 {
 #if defined (G_OS_WIN32) && GLIB_SIZEOF_VOID_P == 8
+#ifndef __GTK_DOC_IGNORE__
   gint64       fd;
+#endif
 #else
   gint         fd;
 #endif
@@ -98,6 +100,12 @@ struct _GPollFD
   gushort      revents;
 };
 
+/**
+ * G_POLLFD_FORMAT:
+ *
+ * A format specifier that can be used in printf()-style format strings
+ * when printing the @fd member of a #GPollFD.
+ */
 #ifdef G_OS_WIN32
 #if GLIB_SIZEOF_VOID_P == 8
 #define G_POLLFD_FORMAT "%#I64x"
diff --git a/glib/gregex.h b/glib/gregex.h
index 77d9d04..eff6d60 100644
--- a/glib/gregex.h
+++ b/glib/gregex.h
@@ -292,7 +292,8 @@ GQuark g_regex_error_quark (void);
  * Since: 2.14
  */
 /* Remember to update G_REGEX_COMPILE_MASK in gregex.c after
- * adding a new flag. */
+ * adding a new flag.
+ */
 typedef enum
 {
   G_REGEX_CASELESS          = 1 << 0,
@@ -405,14 +406,20 @@ typedef enum
 /**
  * GRegex:
  *
- * A GRegex is the "compiled" form of a regular expression pattern. This
- * structure is opaque and its fields cannot be accessed directly.
+ * A GRegex is the "compiled" form of a regular expression pattern.
+ * This structure is opaque and its fields cannot be accessed directly.
  *
  * Since: 2.14
  */
 typedef struct _GRegex         GRegex;
 
 
+/**
+ * GMatchInfo:
+ *
+ * A GMatchInfo is an opaque struct used to return information about
+ * matches.
+ */
 typedef struct _GMatchInfo     GMatchInfo;
 
 /**
diff --git a/glib/gscanner.c b/glib/gscanner.c
index e39387b..52b770a 100644
--- a/glib/gscanner.c
+++ b/glib/gscanner.c
@@ -88,6 +88,14 @@
  */
 
 /**
+ * G_CSET_DIGITS:
+ *
+ * The set of ASCII digits.
+ * Used for specifying valid identifier characters
+ * in #GScannerConfig.
+ */
+
+/**
  * G_CSET_LATINC:
  *
  * The set of uppercase ISO 8859-1 alphabet characters
diff --git a/glib/gvariant-parser.c b/glib/gvariant-parser.c
index 7536844..3a8c63d 100644
--- a/glib/gvariant-parser.c
+++ b/glib/gvariant-parser.c
@@ -74,6 +74,8 @@ G_DEFINE_QUARK (g-variant-parse-error-quark, g_variant_parse_error)
 /**
  * g_variant_parser_get_error_quark:
  *
+ * Same as g_variant_error_quark().
+ *
  * Deprecated: Use g_variant_parse_error_quark() instead.
  */
 GQuark
diff --git a/glib/gversion.c b/glib/gversion.c
index b8283db..0a2feed 100644
--- a/glib/gversion.c
+++ b/glib/gversion.c
@@ -49,6 +49,15 @@
  */
 
 /**
+ * glib_major_version:
+ *
+ * The major version of the GLib library.
+ *
+ * An integer variable exported from the library linked
+ * against at application run time.
+ */
+
+/**
  * GLIB_MAJOR_VERSION:
  *
  * The major version number of the GLib library.
@@ -59,6 +68,15 @@
  */
 
 /**
+ * glib_minor_version:
+ *
+ * The minor version number of the GLib library.
+ *
+ * An integer variable exported from the library linked
+ * against at application run time.
+ */
+
+/**
  * GLIB_MINOR_VERSION:
  *
  * The minor version number of the GLib library.
@@ -69,6 +87,15 @@
  */
 
 /**
+ * glib_micro_version:
+ *
+ * The micro version number of the GLib library.
+ *
+ * An integer variable exported from the library linked
+ * against at application run time.
+ */
+
+/**
  * GLIB_MICRO_VERSION:
  *
  * The micro version number of the GLib library.
@@ -91,6 +118,26 @@
  * is the same as or newer than the passed-in version.
  */
 
+/**
+ * glib_binary_age:
+ *
+ * The binary age of the GLib library.
+ * Defines how far back backwards compatibility reaches.
+ *
+ * An integer variable exported from the library linked
+ * against at application run time.
+ */
+
+/**
+ * glib_interface_age:
+ *
+ * The interface age of the GLib library.
+ * Defines how far back the API has last been extended.
+ *
+ * An integer variable exported from the library linked
+ * against at application run time.
+ */
+
 const guint glib_major_version = GLIB_MAJOR_VERSION;
 const guint glib_minor_version = GLIB_MINOR_VERSION;
 const guint glib_micro_version = GLIB_MICRO_VERSION;
diff --git a/gobject/gvalue.c b/gobject/gvalue.c
index 6a0031c..c229ce8 100644
--- a/gobject/gvalue.c
+++ b/gobject/gvalue.c
@@ -296,12 +296,13 @@ g_value_fits_pointer (const GValue *value)
 
 /**
  * g_value_peek_pointer:
- * @value: An initialized #GValue structure.
+ * @value: An initialized #GValue structure
+ *
+ * Returns the value contents as pointer. This function asserts that
+ * g_value_fits_pointer() returned %TRUE for the passed in value.
+ * This is an internal function introduced mainly for C marshallers.
  *
- * Returns: (transfer none): the value contents as pointer. This
- * function asserts that g_value_fits_pointer() returned %TRUE for the
- * passed in value.  This is an internal function introduced mainly
- * for C marshallers.
+ * Returns: (transfer none): the value contents as pointer
  */
 gpointer
 g_value_peek_pointer (const GValue *value)