Merge branch '1760-txt-record-docs' into 'master'

docs: Clarify support for multiple TXT record strings

Closes #1760

See merge request GNOME/glib!797

12 files changed, 51 insertions, 45 deletions

diff --git a/gio/gdbusobjectmanager.c b/gio/gdbusobjectmanager.c
index 0eaec3f8c..3ef622a33 100644
--- a/gio/gdbusobjectmanager.c
+++ b/gio/gdbusobjectmanager.c
@@ -188,7 +188,7 @@ g_dbus_object_manager_get_objects (GDBusObjectManager *manager)
 /**
  * g_dbus_object_manager_get_object:
  * @manager: A #GDBusObjectManager.
- * @object_path: Object path to lookup.
+ * @object_path: Object path to look up.
  *
  * Gets the #GDBusObjectProxy at @object_path, if any.
  *
@@ -209,8 +209,8 @@ g_dbus_object_manager_get_object (GDBusObjectManager *manager,
 /**
  * g_dbus_object_manager_get_interface:
  * @manager: A #GDBusObjectManager.
- * @object_path: Object path to lookup.
- * @interface_name: D-Bus interface name to lookup.
+ * @object_path: Object path to look up.
+ * @interface_name: D-Bus interface name to look up.
  *
  * Gets the interface proxy for @interface_name at @object_path, if
  * any.
diff --git a/gio/gfileattribute.c b/gio/gfileattribute.c
index c3a8ebf4b..0e4bfc28f 100644
--- a/gio/gfileattribute.c
+++ b/gio/gfileattribute.c
@@ -917,7 +917,7 @@ g_file_attribute_info_list_bsearch (GFileAttributeInfoList *list,
 /**
  * g_file_attribute_info_list_lookup:
  * @list: a #GFileAttributeInfoList.
- * @name: the name of the attribute to lookup.
+ * @name: the name of the attribute to look up.
  *
  * Gets the file attribute with the name @name from @list.
  *
diff --git a/gio/gioenums.h b/gio/gioenums.h
index 2fc69b6be..d3ada454a 100644
--- a/gio/gioenums.h
+++ b/gio/gioenums.h
@@ -715,11 +715,11 @@ typedef enum {
 
 /**
  * GResolverRecordType:
- * @G_RESOLVER_RECORD_SRV: lookup DNS SRV records for a domain
- * @G_RESOLVER_RECORD_MX: lookup DNS MX records for a domain
- * @G_RESOLVER_RECORD_TXT: lookup DNS TXT records for a name
- * @G_RESOLVER_RECORD_SOA: lookup DNS SOA records for a zone
- * @G_RESOLVER_RECORD_NS: lookup DNS NS records for a domain
+ * @G_RESOLVER_RECORD_SRV: look up DNS SRV records for a domain
+ * @G_RESOLVER_RECORD_MX: look up DNS MX records for a domain
+ * @G_RESOLVER_RECORD_TXT: look up DNS TXT records for a name
+ * @G_RESOLVER_RECORD_SOA: look up DNS SOA records for a zone
+ * @G_RESOLVER_RECORD_NS: look up DNS NS records for a domain
  *
  * The type of record that g_resolver_lookup_records() or
  * g_resolver_lookup_records_async() should retrieve. The records are returned
@@ -727,24 +727,30 @@ typedef enum {
  * the variant tuples returned.
  *
  * %G_RESOLVER_RECORD_SRV records are returned as variants with the signature
- * '(qqqs)', containing a guint16 with the priority, a guint16 with the
- * weight, a guint16 with the port, and a string of the hostname.
+ * `(qqqs)`, containing a `guint16` with the priority, a `guint16` with the
+ * weight, a `guint16` with the port, and a string of the hostname.
  *
  * %G_RESOLVER_RECORD_MX records are returned as variants with the signature
- * '(qs)', representing a guint16 with the preference, and a string containing
+ * `(qs)`, representing a `guint16` with the preference, and a string containing
  * the mail exchanger hostname.
  *
  * %G_RESOLVER_RECORD_TXT records are returned as variants with the signature
- * '(as)', representing an array of the strings in the text record.
+ * `(as)`, representing an array of the strings in the text record. Note: Most TXT
+ * records only contain a single string, but
+ * [RFC 1035](https://tools.ietf.org/html/rfc1035#section-3.3.14) does allow a
+ * record to contain multiple strings. The RFC which defines the interpretation
+ * of a specific TXT record will likely require concatenation of multiple
+ * strings if they are present, as with
+ * [RFC 7208](https://tools.ietf.org/html/rfc7208#section-3.3).
  *
  * %G_RESOLVER_RECORD_SOA records are returned as variants with the signature
- * '(ssuuuuu)', representing a string containing the primary name server, a
- * string containing the administrator, the serial as a guint32, the refresh
- * interval as guint32, the retry interval as a guint32, the expire timeout
- * as a guint32, and the ttl as a guint32.
+ * `(ssuuuuu)`, representing a string containing the primary name server, a
+ * string containing the administrator, the serial as a `guint32`, the refresh
+ * interval as a `guint32`, the retry interval as a `guint32`, the expire timeout
+ * as a `guint32`, and the TTL as a `guint32`.
  *
  * %G_RESOLVER_RECORD_NS records are returned as variants with the signature
- * '(s)', representing a string of the hostname of the name server.
+ * `(s)`, representing a string of the hostname of the name server.
  *
  * Since: 2.34
  */
diff --git a/gio/gnetworkaddress.c b/gio/gnetworkaddress.c
index 7e46f5e4a..a3ca21a30 100644
--- a/gio/gnetworkaddress.c
+++ b/gio/gnetworkaddress.c
@@ -1347,7 +1347,7 @@ g_network_address_address_enumerator_next_async (GSocketAddressEnumerator  *enum
 
               addr_enum->state = RESOLVE_STATE_WAITING_ON_IPV4 | RESOLVE_STATE_WAITING_ON_IPV6;
               addr_enum->queued_task = g_steal_pointer (&task);
-              /* Lookup in parallel as per RFC 8305 */
+              /* Look up in parallel as per RFC 8305 */
               g_resolver_lookup_by_name_with_flags_async (resolver,
                                                           addr->priv->hostname,
                                                           G_RESOLVER_NAME_LOOKUP_FLAGS_IPV6_ONLY,
diff --git a/gio/gproxy.c b/gio/gproxy.c
index b7e322101..60bb5b8e5 100644
--- a/gio/gproxy.c
+++ b/gio/gproxy.c
@@ -52,8 +52,8 @@ g_proxy_default_init (GProxyInterface *iface)
  * g_proxy_get_default_for_protocol:
  * @protocol: the proxy protocol name (e.g. http, socks, etc)
  *
- * Lookup "gio-proxy" extension point for a proxy implementation that supports
- * specified protocol.
+ * Find the `gio-proxy` extension point for a proxy implementation that supports
+ * the specified protocol.
  *
  * Returns: (transfer full): return a #GProxy or NULL if protocol
  *               is not supported.
diff --git a/gio/gresolver.c b/gio/gresolver.c
index 7f064322b..3e61ccaff 100644
--- a/gio/gresolver.c
+++ b/gio/gresolver.c
@@ -1041,8 +1041,8 @@ g_resolver_free_targets (GList *targets)
 /**
  * g_resolver_lookup_records:
  * @resolver: a #GResolver
- * @rrname: the DNS name to lookup the record for
- * @record_type: the type of DNS record to lookup
+ * @rrname: the DNS name to look up the record for
+ * @record_type: the type of DNS record to look up
  * @cancellable: (nullable): a #GCancellable, or %NULL
  * @error: return location for a #GError, or %NULL
  *
@@ -1086,8 +1086,8 @@ g_resolver_lookup_records (GResolver            *resolver,
 /**
  * g_resolver_lookup_records_async:
  * @resolver: a #GResolver
- * @rrname: the DNS name to lookup the record for
- * @record_type: the type of DNS record to lookup
+ * @rrname: the DNS name to look up the record for
+ * @record_type: the type of DNS record to look up
  * @cancellable: (nullable): a #GCancellable, or %NULL
  * @callback: (scope async): callback to call after resolution completes
  * @user_data: (closure): data for @callback
diff --git a/gio/gsettings-mapping.c b/gio/gsettings-mapping.c
index bba8a8f7c..8c64b02a5 100644
--- a/gio/gsettings-mapping.c
+++ b/gio/gsettings-mapping.c
@@ -498,7 +498,7 @@ g_settings_get_mapping (GValue   *value,
              return TRUE;
             }
 
-          g_warning ("Unable to lookup enum nick '%s' via GType", nick);
+          g_warning ("Unable to look up enum nick ‘%s’ via GType", nick);
           return FALSE;
         }
     }
diff --git a/gio/gtlsdatabase.c b/gio/gtlsdatabase.c
index 58da11df3..f06dabf0a 100644
--- a/gio/gtlsdatabase.c
+++ b/gio/gtlsdatabase.c
@@ -35,7 +35,7 @@
  * @short_description: TLS database type
  * @include: gio/gio.h
  *
- * #GTlsDatabase is used to lookup certificates and other information
+ * #GTlsDatabase is used to look up certificates and other information
  * from a certificate or key store. It is an abstract base class which
  * TLS library specific subtypes override.
  *
@@ -658,7 +658,7 @@ g_tls_database_create_certificate_handle (GTlsDatabase            *self,
  * @cancellable: (nullable): a #GCancellable, or %NULL
  * @error: (nullable): a #GError, or %NULL
  *
- * Lookup a certificate by its handle.
+ * Look up a certificate by its handle.
  *
  * The handle should have been created by calling
  * g_tls_database_create_certificate_handle() on a #GTlsDatabase object of
@@ -709,7 +709,7 @@ g_tls_database_lookup_certificate_for_handle (GTlsDatabase            *self,
  * @callback: callback to call when the operation completes
  * @user_data: the data to pass to the callback function
  *
- * Asynchronously lookup a certificate by its handle in the database. See
+ * Asynchronously look up a certificate by its handle in the database. See
  * g_tls_database_lookup_certificate_for_handle() for more information.
  *
  * Since: 2.30
@@ -777,7 +777,7 @@ g_tls_database_lookup_certificate_for_handle_finish (GTlsDatabase            *se
  * @cancellable: (nullable): a #GCancellable, or %NULL
  * @error: (nullable): a #GError, or %NULL
  *
- * Lookup the issuer of @certificate in the database.
+ * Look up the issuer of @certificate in the database.
  *
  * The #GTlsCertificate:issuer property
  * of @certificate is not modified, and the two certificates are not hooked
@@ -823,7 +823,7 @@ g_tls_database_lookup_certificate_issuer (GTlsDatabase           *self,
  * @callback: callback to call when the operation completes
  * @user_data: the data to pass to the callback function
  *
- * Asynchronously lookup the issuer of @certificate in the database. See
+ * Asynchronously look up the issuer of @certificate in the database. See
  * g_tls_database_lookup_certificate_issuer() for more information.
  *
  * Since: 2.30
@@ -889,7 +889,7 @@ g_tls_database_lookup_certificate_issuer_finish (GTlsDatabase          *self,
  * @cancellable: (nullable): a #GCancellable, or %NULL
  * @error: (nullable): a #GError, or %NULL
  *
- * Lookup certificates issued by this issuer in the database.
+ * Look up certificates issued by this issuer in the database.
  *
  * This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform
  * the lookup operation asynchronously.
@@ -931,7 +931,7 @@ g_tls_database_lookup_certificates_issued_by (GTlsDatabase           *self,
  * @callback: callback to call when the operation completes
  * @user_data: the data to pass to the callback function
  *
- * Asynchronously lookup certificates issued by this issuer in the database. See
+ * Asynchronously look up certificates issued by this issuer in the database. See
  * g_tls_database_lookup_certificates_issued_by() for more information.
  *
  * The database may choose to hold a reference to the issuer byte array for the duration
diff --git a/gio/gvfs.h b/gio/gvfs.h
index 46ad792c8..72fe2dd32 100644
--- a/gio/gvfs.h
+++ b/gio/gvfs.h
@@ -39,7 +39,7 @@ G_BEGIN_DECLS
 /**
  * GVfsFileLookupFunc:
  * @vfs: a #GVfs
- * @identifier: the identifier to lookup a #GFile for. This can either
+ * @identifier: the identifier to look up a #GFile for. This can either
  *     be an URI or a parse name as returned by g_file_get_parse_name()
  * @user_data: user data passed to the function
  *
diff --git a/gio/strinfo.c b/gio/strinfo.c
index cd47215da..f5e92a41d 100644
--- a/gio/strinfo.c
+++ b/gio/strinfo.c
@@ -61,24 +61,24 @@
  *
  * The operations that someone may want to perform with the map:
  *
- *   - lookup if a string is valid (and not an alias)
- *   - lookup the integer value for a enum 'nick'
- *   - lookup the integer value for the target of an alias
- *   - lookup an alias and convert it to its target string
- *   - lookup the enum nick for a given value
+ *   - look up if a string is valid (and not an alias)
+ *   - look up the integer value for a enum 'nick'
+ *   - look up the integer value for the target of an alias
+ *   - look up an alias and convert it to its target string
+ *   - look up the enum nick for a given value
  *
- * In order to lookup if a string is valid, it is padded on either side
+ * In order to look up if a string is valid, it is padded on either side
  * (as described) and scanned for in the array.  For example, you might
  * look for "foo":
  *
  *                   xff 'f' 'o' 'o'   x00 x00 x00 xff
  *
- * In order to lookup the integer value for a nick, the string is padded
+ * In order to look up the integer value for a nick, the string is padded
  * on either side and scanned for in the array, as above.  Instead of
  * merely succeeding, we look at the integer value to the left of the
  * match.  This is the enum value.
  *
- * In order to lookup an alias and convert it to its target enum value,
+ * In order to look up an alias and convert it to its target enum value,
  * the string is padded on either side (as described, with 0xfe) and
  * scanned for.  For example, you might look for "baz":
  *
@@ -92,7 +92,7 @@
  * added past the start of the integer value to find the start of the
  * string.
  *
- * To lookup the enum nick for a given value, the value is searched for
+ * To look up the enum nick for a given value, the value is searched for
  * in the array.  To ensure that the value isn't matching the inside of a
  * string, we must check that it is either the first item in the array or
  * immediately preceded by the byte 0xff.  It must also be immediately
diff --git a/gio/tests/desktop-app-info.c b/gio/tests/desktop-app-info.c
index ed2f89111..f4e509a59 100644
--- a/gio/tests/desktop-app-info.c
+++ b/gio/tests/desktop-app-info.c
@@ -659,7 +659,7 @@ test_search (void)
   assert_search ("konq", "kde4-konqbrowser.desktop\n", TRUE, TRUE, NULL, NULL);
   assert_search ("kate", "kde4-kate.desktop\n", TRUE, TRUE, NULL, NULL);
 
-  /* make sure we can lookup apps by name properly */
+  /* make sure we can look up apps by name properly */
   assert_info ("kde4-kate.desktop",
                "kde4-kate.desktop\n"
                "Kate\n"
diff --git a/gio/tests/resolver.c b/gio/tests/resolver.c
index cebd729e2..c57b81867 100644
--- a/gio/tests/resolver.c
+++ b/gio/tests/resolver.c
@@ -49,7 +49,7 @@ usage (void)
 	fprintf (stderr, "       Use -s to do synchronous lookups.\n");
 	fprintf (stderr, "       Use -c NUMBER (and only a single resolvable argument) to test GSocketConnectable.\n");
 	fprintf (stderr, "       The given NUMBER determines how many times the connectable will be enumerated.\n");
-	fprintf (stderr, "       Use -t with MX, TXT, NS or SOA to lookup DNS records of those types.\n");
+	fprintf (stderr, "       Use -t with MX, TXT, NS or SOA to look up DNS records of those types.\n");
 	exit (1);
 }