From 34dba57c43bf471e9b511cd56d541f5bf58dcc48 Mon Sep 17 00:00:00 2001 From: Murray Cumming Date: Thu, 24 Mar 2011 11:02:27 +0100 Subject: Regenerate the XML for the C API documentation. * gio/src/gio_docs.xml: * glib/src/glib_docs.xml: Regenerated with docextract_to_xml.py. --- ChangeLog | 7 ++ gio/src/gio_docs.xml | 182 +++++++++++++++++++++++++++++-------------------- glib/src/glib_docs.xml | 94 ++++++++++++++++--------- 3 files changed, 176 insertions(+), 107 deletions(-) diff --git a/ChangeLog b/ChangeLog index 2b82b432..c51fa2c5 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2011-03-24 Murray Cumming + + Regenerate the XML for the C API documentation. + + * gio/src/gio_docs.xml: + * glib/src/glib_docs.xml: Regenerated with docextract_to_xml.py. + 2011-03-24 Murray Cumming Gio: Remove SettingsBackend. diff --git a/gio/src/gio_docs.xml b/gio/src/gio_docs.xml index 9379706c..40267388 100644 --- a/gio/src/gio_docs.xml +++ b/gio/src/gio_docs.xml @@ -1415,8 +1415,8 @@ containing the arguments (the argv) -Gets the working directory of the command line invocation. The -string may contain non-utf8 data. +Gets the working directory of the command line invocation. +The string may contain non-utf8 data. It is possible that the remote application did not send a working directory, so this may be %NULL. @@ -1441,8 +1441,9 @@ Since: 2.28 Gets the contents of the 'environ' variable of the command line -invocation, as would be returned by g_get_environ(). The strings may -contain non-utf8 data. +invocation, as would be returned by g_get_environ(), ie as a +%NULL-terminated list of strings in the form 'NAME=VALUE'. +The strings may contain non-utf8 data. The remote application usually does not send an environment. Use %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag @@ -1452,6 +1453,9 @@ to invocation messages from other applications). The return value should not be modified or freed and is valid for as long as @cmdline exists. +See g_application_command_line_getenv() if you are only interested +in the value of a single environment variable. + Since: 2.28 @@ -1745,7 +1749,7 @@ application already exists (the 'primary' instance). Calls to perform actions on @application will result in the actions being performed by the primary instance. -The value of this property can not be accessed before +The value of this property cannot be accessed before g_application_register() has been called. See g_application_get_is_registered(). @@ -1792,9 +1796,9 @@ g_application_set_application_id(). For convenience, the restrictions on application identifiers are reproduced here: <itemizedlist> -<listitem>Application identifiers must contain only the ASCII characters "[A-Z][a-z][0-9]_-" and must not begin with a digit.</listitem> -<listitem>Application identifiers must contain at least one '.' (period) character (and thus at least two elements).</listitem> -<listitem>Application identifiers must not begin with a '.' (period) character.</listitem> +<listitem>Application identifiers must contain only the ASCII characters "[A-Z][a-z][0-9]_-." and must not begin with a digit.</listitem> +<listitem>Application identifiers must contain at least one '.' (period) character (and thus at least three elements).</listitem> +<listitem>Application identifiers must not begin or end with a '.' (period) character.</listitem> <listitem>Application identifiers must not contain consecutive '.' (period) characters.</listitem> <listitem>Application identifiers must not exceed 255 characters.</listitem> </itemizedlist> @@ -1881,7 +1885,7 @@ Attempts registration of the application. This is the point at which the application discovers if it is the primary instance or merely acting as a remote for an already-existing primary instance. This is implemented by attempting to acquire the -application identifier as a uniue bus name on the session bus using +application identifier as a unique bus name on the session bus using GDBus. Due to the internal architecture of GDBus, method calls can be @@ -1948,13 +1952,33 @@ call to g_application_hold(). Runs the application. This function is intended to be run from main() and its return value -is intended to be returned by main(). +is intended to be returned by main(). Although you are expected to pass +the @argc, @argv parameters from main() to this function, it is possible +to pass %NULL if @argv is not available or commandline handling is not +required. -First, the local_command_line() virtual function is invoked. This -function always runs on the local instance. If that function returns -%FALSE then the application is registered and the #GApplication::command-line -signal is emitted in the primary instance (which may or may not be -this instance). +First, the local_command_line() virtual function is invoked. +This function always runs on the local instance. It gets passed a pointer +to a %NULL-terminated copy of @argv and is expected to remove the arguments +that it handled (shifting up remaining arguments). See +<xref linkend="gapplication-example-cmdline2"/> for an example of +parsing @argv manually. Alternatively, you may use the #GOptionContext API, +after setting <literal>argc = g_strv_length (argv);</literal>. + +The last argument to local_command_line() is a pointer to the @status +variable which can used to set the exit status that is returned from +g_application_run(). + +If local_command_line() returns %TRUE, the command line is expected +to be completely handled, including possibly registering as the primary +instance, calling g_application_activate() or g_application_open(), etc. + +If local_command_line() returns %FALSE then the application is registered +and the #GApplication::command-line signal is emitted in the primary +instance (which may or may not be this instance). The signal handler +gets passed a #GApplicationCommandline object that (among other things) +contains the remaining commandline arguments that have not been handled +by local_command_line(). If the application has the %G_APPLICATION_HANDLES_COMMAND_LINE flag set then the default implementation of local_command_line() @@ -1970,9 +1994,17 @@ g_application_activate() is called. If commandline arguments are given and the %G_APPLICATION_HANDLES_OPEN flag is set then they are assumed to be filenames and g_application_open() is called. +If you need to handle commandline arguments that are not filenames, +and you don't mind commandline handling to happen in the primary +instance, you should set %G_APPLICATION_HANDLED_COMMAND_LINE and +process the commandline arguments in your #GApplication::command-line +signal handler, either manually or using the #GOptionContext API. + If you are interested in doing more complicated local handling of the commandline then you should implement your own #GApplication subclass -and override local_command_line(). See +and override local_command_line(). In this case, you most likely want +to return %TRUE from your local_command_line() implementation to +suppress the default handling. See <xref linkend="gapplication-example-cmdline2"/> for an example. If, after the above is done, the use count of the application is zero @@ -1993,11 +2025,11 @@ Since: 2.28 - the argc from main() + the argc from main() (or 0 if @argv is %NULL) - the argv from main() + the argv from main(), or %NULL @@ -11503,9 +11535,9 @@ falls to zero, the @list is deleted. Checks if the matcher will match all of the keys in a given namespace. -This will always return %TRUE if a wildcard character is in use (e.g. if +This will always return %TRUE if a wildcard character is in use (e.g. if matcher was created with "standard::*" and @ns is "standard", or if matcher was created -using "*" and namespace is anything.) +using "*" and namespace is anything.) TODO: this is awkwardly worded. @@ -11538,14 +11570,14 @@ Gets the next matched attribute from a #GFileAttributeMatcher. - a string containing the next attribute or %NULL if + a string containing the next attribute or %NULL if no more attribute exist. -Checks if an attribute will be matched by an attribute matcher. If +Checks if an attribute will be matched by an attribute matcher. If the matcher was created with the "*" matching string, this function will always return %TRUE. @@ -11588,17 +11620,17 @@ returns %FALSE if "*" was used when creating the matcher. -Creates a new file attribute matcher, which matches attributes -against a given string. #GFileAttributeMatcher<!-- -->s are reference -counted structures, and are created with a reference count of 1. If -the number of references falls to 0, the #GFileAttributeMatcher is +Creates a new file attribute matcher, which matches attributes +against a given string. #GFileAttributeMatcher<!-- -->s are reference +counted structures, and are created with a reference count of 1. If +the number of references falls to 0, the #GFileAttributeMatcher is automatically destroyed. The @attribute string should be formatted with specific keys separated -from namespaces with a double colon. Several "namespace::key" strings may be -concatenated with a single comma (e.g. "standard::type,standard::is-hidden"). -The wildcard "*" may be used to match all keys and namespaces, or -"namespace::*" will match all keys in a given namespace. +from namespaces with a double colon. Several "namespace::key" strings may be +concatenated with a single comma (e.g. "standard::type,standard::is-hidden"). +The wildcard "*" may be used to match all keys and namespaces, or +"namespace::*" will match all keys in a given namespace. Examples of strings to use: <table> @@ -11643,7 +11675,7 @@ References a file attribute matcher. -Unreferences @matcher. If the reference count falls below 1, +Unreferences @matcher. If the reference count falls below 1, the @matcher is automatically freed. @@ -13271,13 +13303,13 @@ contain a boolean value, %FALSE will be returned. - the boolean value contained within the attribute. + the boolean value contained within the attribute. -Gets the value of a byte string attribute. If the attribute does +Gets the value of a byte string attribute. If the attribute does not contain a byte string, %NULL will be returned. @@ -13292,7 +13324,7 @@ not contain a byte string, %NULL will be returned. - the contents of the @attribute value as a byte string, or + the contents of the @attribute value as a byte string, or %NULL otherwise. @@ -13325,15 +13357,15 @@ Gets the attribute type, value and status for an attribute key. - %TRUE if @info has an attribute named @attribute, + %TRUE if @info has an attribute named @attribute, %FALSE otherwise. -Gets a signed 32-bit integer contained within the attribute. If the -attribute does not contain a signed 32-bit integer, or is invalid, +Gets a signed 32-bit integer contained within the attribute. If the +attribute does not contain a signed 32-bit integer, or is invalid, 0 will be returned. @@ -13354,8 +13386,8 @@ attribute does not contain a signed 32-bit integer, or is invalid, -Gets a signed 64-bit integer contained within the attribute. If the -attribute does not contain an signed 64-bit integer, or is invalid, +Gets a signed 64-bit integer contained within the attribute. If the +attribute does not contain an signed 64-bit integer, or is invalid, 0 will be returned. @@ -13370,13 +13402,13 @@ attribute does not contain an signed 64-bit integer, or is invalid, - a signed 64-bit integer from the attribute. + a signed 64-bit integer from the attribute. -Gets the value of a #GObject attribute. If the attribute does +Gets the value of a #GObject attribute. If the attribute does not contain a #GObject, %NULL will be returned. @@ -13412,7 +13444,7 @@ Gets the attribute status for an attribute key. - a #GFileAttributeStatus for the given @attribute, or + a #GFileAttributeStatus for the given @attribute, or %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid. @@ -13420,7 +13452,7 @@ Gets the attribute status for an attribute key. -Gets the value of a string attribute. If the attribute does +Gets the value of a string attribute. If the attribute does not contain a string, %NULL will be returned. @@ -13435,7 +13467,7 @@ not contain a string, %NULL will be returned. - the contents of the @attribute value as a string, or + the contents of the @attribute value as a UTF-8 string, or %NULL otherwise. @@ -13459,7 +13491,7 @@ Since: 2.22 the contents of the @attribute value as a stringv, or -%NULL otherwise. Do not free. +%NULL otherwise. Do not free. These returned strings are UTF-8. @@ -13480,15 +13512,15 @@ Gets the attribute type for an attribute key. - a #GFileAttributeType for the given @attribute, or + a #GFileAttributeType for the given @attribute, or %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set. -Gets an unsigned 32-bit integer contained within the attribute. If the -attribute does not contain an unsigned 32-bit integer, or is invalid, +Gets an unsigned 32-bit integer contained within the attribute. If the +attribute does not contain an unsigned 32-bit integer, or is invalid, 0 will be returned. @@ -13503,14 +13535,14 @@ attribute does not contain an unsigned 32-bit integer, or is invalid, - an unsigned 32-bit integer from the attribute. + an unsigned 32-bit integer from the attribute. -Gets a unsigned 64-bit integer contained within the attribute. If the -attribute does not contain an unsigned 64-bit integer, or is invalid, +Gets a unsigned 64-bit integer contained within the attribute. If the +attribute does not contain an unsigned 64-bit integer, or is invalid, 0 will be returned. @@ -13525,7 +13557,7 @@ attribute does not contain an unsigned 64-bit integer, or is invalid, - a unsigned 64-bit integer from the attribute. + a unsigned 64-bit integer from the attribute. @@ -13579,7 +13611,7 @@ Gets the edit name for a file. -Gets the <link linkend="gfile-etag">entity tag</link> for a given +Gets the <link linkend="gfile-etag">entity tag</link> for a given #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE. @@ -13596,7 +13628,7 @@ Gets the <link linkend="gfile-etag">entity tag</link> for -Gets a file's type (whether it is a regular file, symlink, etc). +Gets a file's type (whether it is a regular file, symlink, etc). This is different from the file's content type, see g_file_info_get_content_type(). @@ -13722,7 +13754,7 @@ Gets the file's size. - a #goffset containing the file's size. + a #goffset containing the file's size. @@ -13775,7 +13807,7 @@ Checks if a file info structure has an attribute named @attribute. - %TRUE if @Ginfo has an attribute named @attribute, + %TRUE if @Ginfo has an attribute named @attribute, %FALSE otherwise. @@ -13820,8 +13852,8 @@ Lists the file info structure's attributes. - a null-terminated array of strings of all of the -possible attribute types for the given @name_space, or + a null-terminated array of strings of all of the +possible attribute types for the given @name_space, or %NULL on error. @@ -13884,7 +13916,7 @@ Sets the @attribute to contain the given value, if possible. -Sets the @attribute to contain the given @attr_value, +Sets the @attribute to contain the given @attr_value, if possible. @@ -13907,7 +13939,7 @@ if possible. -Sets the @attribute to contain the given @attr_value, +Sets the @attribute to contain the given @attr_value, if possible. @@ -13930,7 +13962,7 @@ if possible. -Sets the @attribute to contain the given @attr_value, +Sets the @attribute to contain the given @attr_value, if possible. @@ -13953,7 +13985,7 @@ if possible. -Sets the @attribute to contain the given @attr_value, +Sets the @attribute to contain the given @attr_value, if possible. @@ -13995,7 +14027,7 @@ Sets @mask on @info to match specific attribute types. -Sets the @attribute to contain the given @attr_value, +Sets the @attribute to contain the given @attr_value, if possible. @@ -14049,7 +14081,7 @@ Since: 2.22 -Sets the @attribute to contain the given @attr_value, +Sets the @attribute to contain the given @attr_value, if possible. @@ -14063,7 +14095,7 @@ if possible. - a string. + a UTF-8 string. @@ -14084,11 +14116,11 @@ Sinze: 2.22 - a file attribute key. + a file attribute key - a %NULL terminated string array + a %NULL terminated array of UTF-8 strings. @@ -14097,7 +14129,7 @@ Sinze: 2.22 -Sets the @attribute to contain the given @attr_value, +Sets the @attribute to contain the given @attr_value, if possible. @@ -14120,7 +14152,7 @@ if possible. -Sets the @attribute to contain the given @attr_value, +Sets the @attribute to contain the given @attr_value, if possible. @@ -14219,7 +14251,7 @@ See %G_FILE_ATTRIBUTE_STANDARD_TYPE. -Sets the icon for a given #GFileInfo. +Sets the icon for a given #GFileInfo. See %G_FILE_ATTRIBUTE_STANDARD_ICON. @@ -14295,7 +14327,7 @@ info to the given time value. -Sets the name attribute for the current #GFileInfo. +Sets the name attribute for the current #GFileInfo. See %G_FILE_ATTRIBUTE_STANDARD_NAME. @@ -14314,7 +14346,7 @@ See %G_FILE_ATTRIBUTE_STANDARD_NAME. -Sets the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute in the file info +Sets the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute in the file info to the given size. @@ -14333,7 +14365,7 @@ to the given size. -Sets the sort order attribute in the file info structure. See +Sets the sort order attribute in the file info structure. See %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER. @@ -14352,7 +14384,7 @@ Sets the sort order attribute in the file info structure. See -Sets the %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET attribute in the file info +Sets the %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET attribute in the file info to the given symlink target. @@ -32834,7 +32866,7 @@ require it. Creates a new #GvdbTable from the contents of the file found at @filename. -The only time this function fails is if the file can not be opened. +The only time this function fails is if the file cannot be opened. In that case, the #GError that is returned will be an error from g_mapped_file_new(). diff --git a/glib/src/glib_docs.xml b/glib/src/glib_docs.xml index a31d6881..5d4f054a 100644 --- a/glib/src/glib_docs.xml +++ b/glib/src/glib_docs.xml @@ -7694,7 +7694,7 @@ to be valid UTF-8. The display name might not be identical to the filename, for instance there might be problems converting it to UTF-8, and some files can be translated in the display. -If GLib can not make sense of the encoding of @filename, as a last resort it +If GLib cannot make sense of the encoding of @filename, as a last resort it replaces unknown characters with U+FFFD, the Unicode replacement character. You can search the result for the UTF-8 encoding of this character (which is "\357\277\275" in octal notation) to find out if @filename was in an invalid @@ -7729,7 +7729,7 @@ and use the return value of this function only for display purposes. Unlike g_filename_to_utf8(), the result is guaranteed to be non-%NULL even if the filename actually isn't in the GLib file name encoding. -If GLib can not make sense of the encoding of @filename, as a last resort it +If GLib cannot make sense of the encoding of @filename, as a last resort it replaces unknown characters with U+FFFD, the Unicode replacement character. You can search the result for the UTF-8 encoding of this character (which is "\357\277\275" in octal notation) to find out if @filename was in an invalid @@ -9052,7 +9052,8 @@ is useful if you need to free the memory allocated for the original key, for example before calling g_hash_table_remove(). You can actually pass %NULL for @lookup_key to test -whether the %NULL key exists. +whether the %NULL key exists, provided the hash and equal functions +of @hash_table are %NULL-safe. @@ -17630,7 +17631,7 @@ argument. <note><para>@destructor is used quite differently from @notify in g_static_private_set().</para></note> -<note><para>A #GPrivate can not be freed. Reuse it instead, if you +<note><para>A #GPrivate cannot be freed. Reuse it instead, if you can, to avoid shortage, or use #GStaticPrivate.</para></note> <note><para>This function will abort if g_thread_init() has not been @@ -18126,7 +18127,6 @@ Since: 2.22 This is just like the standard C qsort() function, but the comparison routine accepts a user data argument. - @@ -27408,7 +27408,7 @@ tasks to be processed by a priority determined by @func, and not just in the order in which they were added to the pool. Note, if the maximum number of threads is more than 1, the order -that threads are executed can not be guranteed 100%. Threads are +that threads are executed cannot be guranteed 100%. Threads are scheduled by the operating system and are executed at random. It cannot be assumed that threads are executed in the order they are created. @@ -27636,15 +27636,15 @@ Since: 2.26 -Finds an the interval within @tz that corresponds to the given @time. -The meaning of @time depends on @type. +Finds an the interval within @tz that corresponds to the given @time_. +The meaning of @time_ depends on @type. If @type is %G_TIME_TYPE_UNIVERSAL then this function will always succeed (since universal time is monotonic and continuous). -Otherwise @time is treated is local time. The distinction between +Otherwise @time_ is treated is local time. The distinction between %G_TIME_TYPE_STANDARD and %G_TIME_TYPE_DAYLIGHT is ignored except in -the case that the given @time is ambiguous. In Toronto, for example, +the case that the given @time_ is ambiguous. In Toronto, for example, 01:30 on November 7th 2010 occured twice (once inside of daylight savings time and the next, an hour later, outside of daylight savings time). In this case, the different value of @type would result in a @@ -27664,15 +27664,15 @@ Since: 2.26 - the #GTimeType of @time + the #GTimeType of @time_ - + a number of seconds since January 1, 1970 - the interval containing @time, or -1 in case of failure + the interval containing @time_, or -1 in case of failure @@ -27985,6 +27985,10 @@ g_timeout_source_new_seconds() and attaches it to the main loop context using g_source_attach(). You can do these steps manually if you need greater control. Also see g_timout_add_seconds_full(). +Note that the first call of the timer may not be precise for timeouts +of one second. If you need finer precision and have such a timeout, +you may want to use g_timeout_add() instead. + Since: 2.14 @@ -30690,7 +30694,7 @@ It typically only makes sense to do this on a stack-allocated through. This function need not be called if you call g_variant_builder_end() and it also doesn't need to be called on builders allocated with g_variant_builder_new (see -g_variant_builder_free() for that). +g_variant_builder_unref() for that). This function leaves the #GVariantBuilder structure set to all-zeros. It is valid to call this function on either an initialised @@ -30958,7 +30962,7 @@ ordered in the usual way. Strings are in ASCII lexographical order. It is a programmer error to attempt to compare container values or two values that have types that are not exactly equal. For example, -you can not compare a 32-bit signed integer with a 32-bit unsigned +you cannot compare a 32-bit signed integer with a 32-bit unsigned integer. Also note that this function is not particularly well-behaved when it comes to comparison of doubles; in particular, the handling of incomparable values (ie: NaN) is undefined. @@ -31412,8 +31416,8 @@ It is an error to call this function with a @value of any type other than %G_VARIANT_TYPE_HANDLE. By convention, handles are indexes into an array of file descriptors -that are sent alongside a DBus message. If you're not interacting -with DBus, you probably don't need them. +that are sent alongside a D-Bus message. If you're not interacting +with D-Bus, you probably don't need them. Since: 2.24 @@ -31787,7 +31791,7 @@ Since: 2.24 - a variant #GVariance instance + a variant #GVariant instance @@ -31887,8 +31891,8 @@ Since: 2.24 -Determines if a given string is a valid DBus object path. You -should ensure that a string is a valid DBus object path before +Determines if a given string is a valid D-Bus object path. You +should ensure that a string is a valid D-Bus object path before passing it to g_variant_new_object_path(). A valid object path starts with '/' followed by zero or more @@ -31905,7 +31909,7 @@ Since: 2.24 - %TRUE if @string is a DBus object path + %TRUE if @string is a D-Bus object path @@ -31932,11 +31936,11 @@ Since: 2.24 -Determines if a given string is a valid DBus type signature. You -should ensure that a string is a valid DBus type signature before +Determines if a given string is a valid D-Bus type signature. You +should ensure that a string is a valid D-Bus type signature before passing it to g_variant_new_signature(). -DBus type signatures consist of zero or more definite #GVariantType +D-Bus type signatures consist of zero or more definite #GVariantType strings in sequence. Since: 2.24 @@ -31948,7 +31952,7 @@ Since: 2.24 - %TRUE if @string is a DBus type signature + %TRUE if @string is a D-Bus type signature @@ -32618,8 +32622,8 @@ Since: 2.24 Creates a new handle #GVariant instance. By convention, handles are indexes into an array of file descriptors -that are sent alongside a DBus message. If you're not interacting -with DBus, you probably don't need them. +that are sent alongside a D-Bus message. If you're not interacting +with D-Bus, you probably don't need them. Since: 2.24 @@ -32717,8 +32721,8 @@ Since: 2.24 -Creates a DBus object path #GVariant with the contents of @string. -@string must be a valid DBus object path. Use +Creates a D-Bus object path #GVariant with the contents of @string. +@string must be a valid D-Bus object path. Use g_variant_is_object_path() if you're not sure. Since: 2.24 @@ -32815,8 +32819,8 @@ or by passing it to another g_variant_new() call. -Creates a DBus type signature #GVariant with the contents of -@string. @string must be a valid DBus type signature. Use +Creates a D-Bus type signature #GVariant with the contents of +@string. @string must be a valid D-Bus type signature. Use g_variant_is_signature() if you're not sure. Since: 2.24 @@ -33024,7 +33028,7 @@ Since: 2.24 - a #GVariance instance + a #GVariant instance @@ -34381,4 +34385,30 @@ of your program. + + +This function is a variant of glib_gettext() which supports +a disambiguating message context. See g_dpgettext() for full +details. + +This is an internal function and should only be used by +the internals of glib (such as libgio). + + + + + + a combined message context and message id, separated +by a \004 character + + + + the offset of the message id in @msgctxid + + + + the transation of @str to the current locale + + + -- cgit v1.2.1