Merge branch 'docs-fixes' into 'master'

Various minor docs fixes

See merge request GNOME/glib!536

docs/reference/glib/gvariant-text.xml

@@ -465,7 +465,7 @@
     parses successfully.  You would need to specify <literal>[&lt;['']&gt;, &lt;@as []&gt;]</literal>.
    </para>
    <para>
-    <literal>{"title": &lt;"frobit"&gt;, "enabled": &lt;true&gt;, width: &lt;800&gt;}</literal> is an example of
+    <literal>{"title": &lt;"frobit"&gt;, "enabled": &lt;true&gt;, "width": &lt;800&gt;}</literal> is an example of
     perhaps the most pervasive use of both dictionaries and variants.
    </para>
   </refsect2>

gio/gmountoperation.h

@@ -66,9 +66,12 @@ struct _GMountOperationClass
 
   /**
    * GMountOperationClass::ask_question:
-   * @op:
+   * @op: a #GMountOperation
-   * @message:
+   * @message: string containing a message to display to the user
-   * @choices: (array zero-terminated=1) (element-type utf8):
+   * @choices: (array zero-terminated=1) (element-type utf8): an array of
+   *    strings for each possible choice
+   *
+   * Virtual implementation of #GMountOperation::ask-question.
    */
   void (* ask_question) (GMountOperation       *op,
 			 const char            *message,
@@ -81,10 +84,14 @@ struct _GMountOperationClass
 
   /**
    * GMountOperationClass::show_processes:
-   * @op:
+   * @op: a #GMountOperation
-   * @message:
+   * @message: string containing a message to display to the user
-   * @processes: (element-type GPid):
+   * @processes: (element-type GPid): an array of #GPid for processes blocking
-   * @choices: (array zero-terminated=1) (element-type utf8):
+   *    the operation
+   * @choices: (array zero-terminated=1) (element-type utf8): an array of
+   *    strings for each possible choice
+   *
+   * Virtual implementation of #GMountOperation::show-processes.
    *
    * Since: 2.22
    */

gio/gproxyaddressenumerator.c

@@ -37,6 +37,22 @@
 #include "gsocketaddressenumerator.h"
 #include "gsocketconnectable.h"
 
+/**
+ * SECTION:gproxyaddressenumerator
+ * @short_description: Proxy wrapper enumerator for socket addresses
+ * @include: gio/gio.h
+ *
+ * #GProxyAddressEnumerator is a wrapper around #GSocketAddressEnumerator which
+ * takes the #GSocketAddress instances returned by the #GSocketAddressEnumerator
+ * and wraps them in #GProxyAddress instances, using the given
+ * #GProxyAddressEnumerator:proxy-resolver.
+ *
+ * This enumerator will be returned (for example, by
+ * g_socket_connectable_enumerate()) as appropriate when a proxy is configured;
+ * there should be no need to manually wrap a #GSocketAddressEnumerator instance
+ * with one.
+ */
+
 #define GET_PRIVATE(o) (G_PROXY_ADDRESS_ENUMERATOR (o)->priv)
 
 enum

gio/gproxyaddressenumerator.h

@@ -49,12 +49,19 @@ typedef struct _GProxyAddressEnumeratorPrivate GProxyAddressEnumeratorPrivate;
 
 struct _GProxyAddressEnumerator
 {
+  /*< private >*/
   GSocketAddressEnumerator parent_instance;
   GProxyAddressEnumeratorPrivate *priv;
 };
 
+/**
+ * GProxyAddressEnumeratorClass:
+ *
+ * Class structure for #GProxyAddressEnumerator.
+ */
 struct _GProxyAddressEnumeratorClass
 {
+  /*< private >*/
   GSocketAddressEnumeratorClass parent_class;
 
   void (*_g_reserved1) (void);

gio/gsocketaddressenumerator.c

@@ -22,6 +22,26 @@
 
 #include "gtask.h"
 
+/**
+ * SECTION:gsocketaddressenumerator
+ * @short_description: Enumerator for socket addresses
+ * @include: gio/gio.h
+ *
+ * #GSocketAddressEnumerator is an enumerator type for #GSocketAddress
+ * instances. It is returned by enumeration functions such as
+ * g_socket_connectable_enumerate(), which returns a #GSocketAddressEnumerator
+ * to list all the #GSocketAddresses which could be used to connect to that
+ * #GSocketConnectable.
+ *
+ * Enumeration is typically a blocking operation, so the asynchronous methods
+ * g_socket_address_enumerator_next_async() and
+ * g_socket_address_enumerator_next_finish() should be used where possible.
+ *
+ * Each #GSocketAddressEnumerator can only be enumerated once. Once
+ * g_socket_address_enumerator_next() has returned %NULL (and no error), further
+ * enumeration with that #GSocketAddressEnumerator is not possible, and it can
+ * be unreffed.
+ */
 
 G_DEFINE_ABSTRACT_TYPE (GSocketAddressEnumerator, g_socket_address_enumerator, G_TYPE_OBJECT)
 

gio/gsocketaddressenumerator.h

@@ -44,14 +44,24 @@ typedef struct _GSocketAddressEnumeratorClass GSocketAddressEnumeratorClass;
 
 struct _GSocketAddressEnumerator
 {
+  /*< private >*/
   GObject parent_instance;
-
 };
 
+/**
+ * GSocketAddressEnumeratorClass:
+ * @next: Virtual method for g_socket_address_enumerator_next().
+ * @next_async: Virtual method for g_socket_address_enumerator_next_async().
+ * @next_finish: Virtual method for g_socket_address_enumerator_next_finish().
+ *
+ * Class structure for #GSocketAddressEnumerator.
+ */
 struct _GSocketAddressEnumeratorClass
 {
+  /*< private >*/
   GObjectClass parent_class;
 
+  /*< public >*/
   /* Virtual Table */
 
   GSocketAddress * (* next)        (GSocketAddressEnumerator  *enumerator,

glib/grefstring.h

@@ -39,6 +39,19 @@ void    g_ref_string_release    (char       *str);
 GLIB_AVAILABLE_IN_2_58
 gsize   g_ref_string_length     (char       *str);
 
+/**
+ * GRefString:
+ *
+ * A typedef for a reference-counted string. A pointer to a #GRefString can be
+ * treated like a standard `char*` array by all code, but can additionally have
+ * `g_ref_string_*()` methods called on it. `g_ref_string_*()` methods cannot be
+ * called on `char*` arrays not allocated using g_ref_string_new().
+ *
+ * If using #GRefString with autocleanups, g_autoptr() must be used rather than
+ * g_autofree(), so that the reference counting metadata is also freed.
+ *
+ * Since: 2.58
+ */
 typedef char GRefString;
 
 G_END_DECLS