diff --git a/gio/gproxyaddressenumerator.c b/gio/gproxyaddressenumerator.c
index 98987f227..bf9215b8f 100644
--- a/gio/gproxyaddressenumerator.c
+++ b/gio/gproxyaddressenumerator.c
@@ -42,19 +42,18 @@
 #include "gsocketconnectable.h"
 
 /**
- * SECTION:gproxyaddressenumerator
- * @short_description: Proxy wrapper enumerator for socket addresses
- * @include: gio/gio.h
+ * GProxyAddressEnumerator:
  *
- * #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.
+ * `GProxyAddressEnumerator` is a wrapper around
+ * [class@Gio.SocketAddressEnumerator] which takes the [class@Gio.SocketAddress]
+ * instances returned by the [class@Gio.SocketAddressEnumerator]
+ * and wraps them in [class@Gio.ProxyAddress] instances, using the given
+ * [property@Gio.ProxyAddressEnumerator: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.
+ * [method@Gio.SocketConnectable.enumerate]) as appropriate when a proxy is
+ * configured; there should be no need to manually wrap a
+ * [class@Gio.SocketAddressEnumerator] instance with one.
  */
 
 #define GET_PRIVATE(o) (G_PROXY_ADDRESS_ENUMERATOR (o)->priv)
diff --git a/gio/gproxyaddressenumerator.h b/gio/gproxyaddressenumerator.h
index b8d36a685..7d36ef03e 100644
--- a/gio/gproxyaddressenumerator.h
+++ b/gio/gproxyaddressenumerator.h
@@ -38,14 +38,6 @@ G_BEGIN_DECLS
 #define G_IS_PROXY_ADDRESS_ENUMERATOR_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_PROXY_ADDRESS_ENUMERATOR))
 #define G_PROXY_ADDRESS_ENUMERATOR_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_PROXY_ADDRESS_ENUMERATOR, GProxyAddressEnumeratorClass))
 
-/**
- * GProxyAddressEnumerator:
- *
- * A subclass of #GSocketAddressEnumerator that takes another address
- * enumerator and wraps each of its results in a #GProxyAddress as
- * directed by the default #GProxyResolver.
- */
-
 typedef struct _GProxyAddressEnumeratorClass GProxyAddressEnumeratorClass;
 typedef struct _GProxyAddressEnumeratorPrivate GProxyAddressEnumeratorPrivate;