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

docs: Clarify support for multiple TXT record strings

Closes #1760

See merge request GNOME/glib!797

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.
+ * @object_path: Object path to look up.
- * @interface_name: D-Bus interface name to lookup.
+ * @interface_name: D-Bus interface name to look up.
  *
  * Gets the interface proxy for @interface_name at @object_path, if
  * any.

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.
  *

gio/gioenums.h

@@ -715,11 +715,11 @@ typedef enum {
 
 /**
  * GResolverRecordType:
- * @G_RESOLVER_RECORD_SRV: lookup DNS SRV records for a domain
+ * @G_RESOLVER_RECORD_SRV: look up DNS SRV records for a domain
- * @G_RESOLVER_RECORD_MX: lookup DNS MX records for a domain
+ * @G_RESOLVER_RECORD_MX: look up DNS MX records for a domain
- * @G_RESOLVER_RECORD_TXT: lookup DNS TXT records for a name
+ * @G_RESOLVER_RECORD_TXT: look up DNS TXT records for a name
- * @G_RESOLVER_RECORD_SOA: lookup DNS SOA records for a zone
+ * @G_RESOLVER_RECORD_SOA: look up DNS SOA records for a zone
- * @G_RESOLVER_RECORD_NS: lookup DNS NS records for a domain
+ * @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
+ * `(qqqs)`, containing a `guint16` with the priority, a `guint16` with the
- * weight, a guint16 with the port, and a string of the hostname.
+ * 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
+ * `(ssuuuuu)`, representing a string containing the primary name server, a
- * string containing the administrator, the serial as a guint32, the refresh
+ * string containing the administrator, the serial as a `guint32`, the refresh
- * interval as guint32, the retry interval as a guint32, the expire timeout
+ * interval as a `guint32`, the retry interval as a `guint32`, the expire timeout
- * as a guint32, and the ttl as a guint32.
+ * 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
  */

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,

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
+ * Find the `gio-proxy` extension point for a proxy implementation that supports
- * specified protocol.
+ * the specified protocol.
  *
  * Returns: (transfer full): return a #GProxy or NULL if protocol
  *               is not supported.

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
+ * @rrname: the DNS name to look up the record for
- * @record_type: the type of DNS record to lookup
+ * @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
+ * @rrname: the DNS name to look up the record for
- * @record_type: the type of DNS record to lookup
+ * @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

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;
         }
     }

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

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
  *

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)
+ *   - look up if a string is valid (and not an alias)
- *   - lookup the integer value for a enum 'nick'
+ *   - look up the integer value for a enum 'nick'
- *   - lookup the integer value for the target of an alias
+ *   - look up the integer value for the target of an alias
- *   - lookup an alias and convert it to its target string
+ *   - look up an alias and convert it to its target string
- *   - lookup the enum nick for a given value
+ *   - 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

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"

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);
 }
 

glib/ghash.c

@@ -86,7 +86,7 @@
  * To insert a key and value into a #GHashTable, use
  * g_hash_table_insert().
  *
- * To lookup a value corresponding to a given key, use
+ * To look up a value corresponding to a given key, use
  * g_hash_table_lookup() and g_hash_table_lookup_extended().
  *
  * g_hash_table_lookup_extended() can also be used to simply
@@ -428,7 +428,7 @@ g_hash_table_hash_to_index (GHashTable *hash_table, guint hash)
 /*
  * g_hash_table_lookup_node:
  * @hash_table: our #GHashTable
- * @key: the key to lookup against
+ * @key: the key to look up against
  * @hash_return: key hash return location
  *
  * Performs a lookup in the hash table, preserving extra information

glib/gmain.c

@@ -2203,7 +2203,7 @@ g_source_unref (GSource *source)
  *
  * Finds a #GSource given a pair of context and ID.
  *
- * It is a programmer error to attempt to lookup a non-existent source.
+ * It is a programmer error to attempt to look up a non-existent source.
  *
  * More specifically: source IDs can be reissued after a source has been
  * destroyed and therefore it is never valid to use this function with a

glib/gscanner.c

@@ -1533,7 +1533,7 @@ g_scanner_unexp_token (GScanner		*scanner,
 		   "%s%s",
 		   need_valid ? "valid " : "",
 		   symbol_spec);
-      /* FIXME: should we attempt to lookup the symbol_name for symbol_2_token? */
+      /* FIXME: should we attempt to look up the symbol_name for symbol_2_token? */
       break;
     case G_TOKEN_CHAR:
       _g_snprintf (expected_string, expected_string_len, "%scharacter",

glib/gsequence.c

@@ -827,7 +827,7 @@ g_sequence_search (GSequence        *seq,
 /**
  * g_sequence_lookup:
  * @seq: a #GSequence
- * @data: data to lookup
+ * @data: data to look up
  * @cmp_func: the function used to compare items in the sequence
  * @cmp_data: user data passed to @cmp_func
  *
@@ -1115,7 +1115,7 @@ g_sequence_search_iter (GSequence                *seq,
 /**
  * g_sequence_lookup_iter:
  * @seq: a #GSequence
- * @data: data to lookup
+ * @data: data to look up
  * @iter_cmp: the function used to compare iterators in the sequence
  * @cmp_data: user data passed to @iter_cmp
  *

glib/gtree.c

@@ -48,7 +48,7 @@
  *
  * To insert a key/value pair into a #GTree use g_tree_insert().
  *
- * To lookup the value corresponding to a given key, use
+ * To look up the value corresponding to a given key, use
  * g_tree_lookup() and g_tree_lookup_extended().
  *
  * To find out the number of nodes in a #GTree, use g_tree_nnodes(). To

glib/gvariant.c

@@ -226,7 +226,7 @@
  * type information would be allocated.
  * 
  * The type information cache, additionally, uses a #GHashTable to
- * store and lookup the cached items and stores a pointer to this
+ * store and look up the cached items and stores a pointer to this
  * hash table in static storage.  The hash table is freed when there
  * are zero items in the type cache.
  *
@@ -942,7 +942,7 @@ g_variant_new_dict_entry (GVariant *key,
 /**
  * g_variant_lookup: (skip)
  * @dictionary: a dictionary #GVariant
- * @key: the key to lookup in the dictionary
+ * @key: the key to look up in the dictionary
  * @format_string: a GVariant format string
  * @...: the arguments to unpack the value into
  *
@@ -1000,7 +1000,7 @@ g_variant_lookup (GVariant    *dictionary,
 /**
  * g_variant_lookup_value:
  * @dictionary: a dictionary #GVariant
- * @key: the key to lookup in the dictionary
+ * @key: the key to look up in the dictionary
  * @expected_type: (nullable): a #GVariantType, or %NULL
  *
  * Looks up a value in a dictionary #GVariant.
@@ -3947,7 +3947,7 @@ g_variant_dict_init (GVariantDict *dict,
 /**
  * g_variant_dict_lookup:
  * @dict: a #GVariantDict
- * @key: the key to lookup in the dictionary
+ * @key: the key to look up in the dictionary
  * @format_string: a GVariant format string
  * @...: the arguments to unpack the value into
  *
@@ -3994,7 +3994,7 @@ g_variant_dict_lookup (GVariantDict *dict,
 /**
  * g_variant_dict_lookup_value:
  * @dict: a #GVariantDict
- * @key: the key to lookup in the dictionary
+ * @key: the key to look up in the dictionary
  * @expected_type: (nullable): a #GVariantType, or %NULL
  *
  * Looks up a value in a #GVariantDict.
@@ -4034,7 +4034,7 @@ g_variant_dict_lookup_value (GVariantDict       *dict,
 /**
  * g_variant_dict_contains:
  * @dict: a #GVariantDict
- * @key: the key to lookup in the dictionary
+ * @key: the key to look up in the dictionary
  *
  * Checks if @key exists in @dict.
  *

gobject/gobject.c

@@ -813,7 +813,7 @@ g_object_class_find_property (GObjectClass *class,
  * g_object_interface_find_property:
  * @g_iface: (type GObject.TypeInterface): any interface vtable for the
  *  interface, or the default vtable for the interface
- * @property_name: name of a property to lookup.
+ * @property_name: name of a property to look up.
  *
  * Find the #GParamSpec with the given name for an
  * interface. Generally, the interface vtable passed in as @g_iface

gobject/gsignal.c

@@ -1243,13 +1243,13 @@ g_signal_lookup (const gchar *name,
     {
       /* give elaborate warnings */
       if (!g_type_name (itype))
-	g_warning (G_STRLOC ": unable to lookup signal \"%s\" for invalid type id '%"G_GSIZE_FORMAT"'",
+	g_warning (G_STRLOC ": unable to look up signal \"%s\" for invalid type id '%"G_GSIZE_FORMAT"'",
 		   name, itype);
       else if (!G_TYPE_IS_INSTANTIATABLE (itype))
-	g_warning (G_STRLOC ": unable to lookup signal \"%s\" for non instantiatable type '%s'",
+	g_warning (G_STRLOC ": unable to look up signal \"%s\" for non instantiatable type '%s'",
 		   name, g_type_name (itype));
       else if (!g_type_class_peek (itype))
-	g_warning (G_STRLOC ": unable to lookup signal \"%s\" of unloaded type '%s'",
+	g_warning (G_STRLOC ": unable to look up signal \"%s\" of unloaded type '%s'",
 		   name, g_type_name (itype));
     }
   

gobject/gtype.c

@@ -3337,9 +3337,9 @@ g_type_qname (GType type)
 
 /**
  * g_type_from_name:
- * @name: type name to lookup
+ * @name: type name to look up
  *
- * Lookup the type ID from a given type name, returning 0 if no type
+ * Look up the type ID from a given type name, returning 0 if no type
  * has been registered under this name (this is the preferred method
  * to find out by name whether a specific type has been registered
  * yet).