[glib: 3/5] gio: Add missing documentation for G{Proxy, Socket}AddressEnumerator

[Philip Withnall <pwithnall src gnome org>]

commit c3fbfbd2bdaed969211e5bccdc219ad926d214c6
Author: Philip Withnall <withnall endlessm com>
Date:   Wed Nov 28 13:10:55 2018 +0000

    gio: Add missing documentation for G{Proxy,Socket}AddressEnumerator
    
    Signed-off-by: Philip Withnall <withnall endlessm com>

 gio/gproxyaddressenumerator.c  | 16 ++++++++++++++++
 gio/gproxyaddressenumerator.h  |  7 +++++++
 gio/gsocketaddressenumerator.c | 20 ++++++++++++++++++++
 gio/gsocketaddressenumerator.h | 12 +++++++++++-
 4 files changed, 54 insertions(+), 1 deletion(-)
---
diff --git a/gio/gproxyaddressenumerator.c b/gio/gproxyaddressenumerator.c
index 74a486e9f..ecf04d110 100644
--- a/gio/gproxyaddressenumerator.c
+++ b/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
diff --git a/gio/gproxyaddressenumerator.h b/gio/gproxyaddressenumerator.h
index 1b99e35c0..de9fa833e 100644
--- a/gio/gproxyaddressenumerator.h
+++ b/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);
diff --git a/gio/gsocketaddressenumerator.c b/gio/gsocketaddressenumerator.c
index 7986f342c..3defc7f89 100644
--- a/gio/gsocketaddressenumerator.c
+++ b/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)
 
diff --git a/gio/gsocketaddressenumerator.h b/gio/gsocketaddressenumerator.h
index f148f6369..2a180fdf5 100644
--- a/gio/gsocketaddressenumerator.h
+++ b/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,