luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-25 15:06:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Don't use the emphasis tag

Browse Source 
Most of the time, the text read just as well without the extra
boldness.
This commit is contained in:
Matthias Clasen 2014-01-31 20:34:33 -05:00
parent 64eface479
commit 4d12e0d66f
36 changed files with 512 additions and 533 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
gio/gasyncresult.c
View File

@ -105,12 +105,11 @@
* <para id="io-priority"><indexterm><primary>I/O * <para id="io-priority"><indexterm><primary>I/O
* priority</primary></indexterm> Many I/O-related asynchronous * priority</primary></indexterm> Many I/O-related asynchronous
* operations have a priority parameter, which is used in certain * operations have a priority parameter, which is used in certain
* cases to determine the order in which operations are executed. They * cases to determine the order in which operations are executed.
* are <emphasis>not</emphasis> used to determine system-wide I/O * They are not used to determine system-wide I/O scheduling.
* scheduling. Priorities are integers, with lower numbers indicating * Priorities are integers, with lower numbers indicating higher priority.
* higher priority. It is recommended to choose priorities between * It is recommended to choose priorities between %G_PRIORITY_LOW and
* %G_PRIORITY_LOW and %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT as a * %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT as a default.</para>
* default. </para>
**/ **/
typedef GAsyncResultIface GAsyncResultInterface; typedef GAsyncResultIface GAsyncResultInterface;

16
gio/gcancellable.c
View File

@ -90,16 +90,14 @@ g_cancellable_class_init (GCancellableClass *klass)
* *
* Note that disconnecting from this signal (or any signal) in a * Note that disconnecting from this signal (or any signal) in a
* multi-threaded program is prone to race conditions. For instance * multi-threaded program is prone to race conditions. For instance
* it is possible that a signal handler may be invoked even * it is possible that a signal handler may be invoked even after
* <emphasis>after</emphasis> a call to * a call to g_signal_handler_disconnect() for that handler has
* g_signal_handler_disconnect() for that handler has already * already returned.
* returned.
* *
* There is also a problem when cancellation happen * There is also a problem when cancellation happens right before
* right before connecting to the signal. If this happens the * connecting to the signal. If this happens the signal will
* signal will unexpectedly not be emitted, and checking before * unexpectedly not be emitted, and checking before connecting to
* connecting to the signal leaves a race condition where this is * the signal leaves a race condition where this is still happening.
* still happening.
* *
* In order to make it safe and easy to connect handlers there * In order to make it safe and easy to connect handlers there
* are two helper functions: g_cancellable_connect() and * are two helper functions: g_cancellable_connect() and

14
gio/gdatainputstream.c
View File

@ -1303,8 +1303,8 @@ g_data_input_stream_read_until_finish (GDataInputStream *stream,
* occurrence of any of the stop characters. * occurrence of any of the stop characters.
* *
* In contrast to g_data_input_stream_read_until(), this function * In contrast to g_data_input_stream_read_until(), this function
* does <emphasis>not</emphasis> consume the stop character. You have * does not consume the stop character. You have to use
* to use g_data_input_stream_read_byte() to get it before calling * g_data_input_stream_read_byte() to get it before calling
* g_data_input_stream_read_upto() again. * g_data_input_stream_read_upto() again.
* *
* Note that @stop_chars may contain '\0' if @stop_chars_len is * Note that @stop_chars may contain '\0' if @stop_chars_len is
@ -1397,8 +1397,8 @@ g_data_input_stream_read_upto (GDataInputStream *stream,
* It is an error to have two outstanding calls to this function. * It is an error to have two outstanding calls to this function.
* *
* In contrast to g_data_input_stream_read_until(), this function * In contrast to g_data_input_stream_read_until(), this function
* does <emphasis>not</emphasis> consume the stop character. You have * does not consume the stop character. You have to use
* to use g_data_input_stream_read_byte() to get it before calling * g_data_input_stream_read_byte() to get it before calling
* g_data_input_stream_read_upto() again. * g_data_input_stream_read_upto() again.
* *
* Note that @stop_chars may contain '\0' if @stop_chars_len is * Note that @stop_chars may contain '\0' if @stop_chars_len is
@ -1437,9 +1437,9 @@ g_data_input_stream_read_upto_async (GDataInputStream *stream,
* Finish an asynchronous call started by * Finish an asynchronous call started by
* g_data_input_stream_read_upto_async(). * g_data_input_stream_read_upto_async().
* *
* Note that this function does <emphasis>not</emphasis> consume the * Note that this function does not consume the stop character. You
* stop character. You have to use g_data_input_stream_read_byte() to * have to use g_data_input_stream_read_byte() to get it before calling
* get it before calling g_data_input_stream_read_upto_async() again. * g_data_input_stream_read_upto_async() again.
* *
* Returns: (transfer full): a string with the data that was read * Returns: (transfer full): a string with the data that was read
* before encountering any of the stop characters. Set @length to * before encountering any of the stop characters. Set @length to

7
gio/gdbusconnection.c
View File

@ -5110,10 +5110,9 @@ obj_message_func (GDBusConnection *connection,
* *
* GDBus automatically implements the standard D-Bus interfaces * GDBus automatically implements the standard D-Bus interfaces
* org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable * org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable
* and org.freedesktop.Peer, so you don't have to implement those for * and org.freedesktop.Peer, so you don't have to implement those for the
* the objects you export. You <emphasis>can</emphasis> implement * objects you export. You can implement org.freedesktop.DBus.Properties
* org.freedesktop.DBus.Properties yourself, e.g. to handle getting * yourself, e.g. to handle getting and setting of properties asynchronously.
* and setting of properties asynchronously.
* *
* Note that the reference count on @interface_info will be * Note that the reference count on @interface_info will be
* incremented by 1 (unless allocated statically, e.g. if the * incremented by 1 (unless allocated statically, e.g. if the

2
gio/gdbusmethodinvocation.c
View File

@ -580,7 +580,7 @@ g_dbus_method_invocation_return_value_with_unix_fd_list (GDBusMethodInvocation *
* applications using GDBus. * applications using GDBus.
* *
* If you are writing an application intended to be portable, * If you are writing an application intended to be portable,
* <emphasis>always</emphasis> register errors with g_dbus_error_register_error() * always register errors with g_dbus_error_register_error()
* or use g_dbus_method_invocation_return_dbus_error(). * or use g_dbus_method_invocation_return_dbus_error().
* *
* This method will free @invocation, you cannot use it afterwards. * This method will free @invocation, you cannot use it afterwards.

13
gio/gdbusobjectmanagerclient.c
View File

@ -91,13 +91,12 @@
* *
* Ultimately, #GDBusObjectManagerClient is used to obtain #GDBusProxy * Ultimately, #GDBusObjectManagerClient is used to obtain #GDBusProxy
* instances. All signals (including the * instances. All signals (including the
* <literal>org.freedesktop.DBus.Properties::PropertiesChanged</literal> * org.freedesktop.DBus.Properties::PropertiesChanged signal)
* signal) delivered to #GDBusProxy instances are guaranteed to * delivered to #GDBusProxy instances are guaranteed to originate
* originate from the name owner. This guarantee along with the * from the name owner. This guarantee along with the behavior
* behavior described above, means that certain race conditions * described above, means that certain race conditions including the
* including the <emphasis><quote>half the proxy is from the old owner * "half the proxy is from the old owner and the other half is from
* and the other half is from the new owner</quote></emphasis> problem * the new owner" problem cannot happen.
* cannot happen.
* *
* To avoid having the application connect to signals on the returned * To avoid having the application connect to signals on the returned
* #GDBusObjectProxy and #GDBusProxy objects, the * #GDBusObjectProxy and #GDBusProxy objects, the

2
gio/gdbusproxy.c
View File

@ -361,7 +361,7 @@ g_dbus_proxy_class_init (GDBusProxyClass *klass)
* Ensure that interactions with this proxy conform to the given * Ensure that interactions with this proxy conform to the given
* interface. This is mainly to ensure that malformed data received * interface. This is mainly to ensure that malformed data received
* from the other peer is ignored. The given #GDBusInterfaceInfo is * from the other peer is ignored. The given #GDBusInterfaceInfo is
* said to be the <emphasis>expected interface</emphasis>. * said to be the "expected interface".
* *
* The checks performed are: * The checks performed are:
* <itemizedlist> * <itemizedlist>

7
gio/gdbusutils.c
View File

@ -562,10 +562,9 @@ g_dbus_gvariant_to_gvalue (GVariant *value,
* #G_TYPE_BOXED derived-types) not in the table above. * #G_TYPE_BOXED derived-types) not in the table above.
* *
* Note that if @gvalue is of type #G_TYPE_VARIANT and its value is * Note that if @gvalue is of type #G_TYPE_VARIANT and its value is
* %NULL, the <emphasis>empty</emphasis> #GVariant instance (never * %NULL, the empty #GVariant instance (never %NULL) for @type is
* %NULL) for @type is returned (e.g. 0 for scalar types, the empty * returned (e.g. 0 for scalar types, the empty string for string types,
* string for string types, <literal>'/'</literal> for object path * '/' for object path types, the empty array for any array type and so on).
* types, the empty array for any array type and so on).
* *
* See the g_dbus_gvariant_to_gvalue() function for how to convert a * See the g_dbus_gvariant_to_gvalue() function for how to convert a
* #GVariant to a #GValue. * #GVariant to a #GValue.

9
gio/gnetworking.c
View File

@ -41,11 +41,10 @@
* want your code to work under both UNIX and Windows, you will need * want your code to work under both UNIX and Windows, you will need
* to take these differences into account. * to take these differences into account.
* *
* Also, under glibc, certain non-portable functions are only visible * Also, under GNU libc, certain non-portable functions are only visible
* in the headers if you define <literal>_GNU_SOURCE</literal> before * in the headers if you define %_GNU_SOURCE before including them. Note
* including them. Note that this symbol must be defined before * that this symbol must be defined before including any headers, or it
* including <emphasis>any</emphasis> headers, or it may not take * may not take effect.
* effect.
*/ */
/** /**

7
gio/gnetworkmonitor.c
View File

@ -262,10 +262,9 @@ g_network_monitor_default_init (GNetworkMonitorInterface *iface)
* connected to a functioning router that has lost its own upstream * connected to a functioning router that has lost its own upstream
* connectivity. Some hosts might only be accessible when a VPN is * connectivity. Some hosts might only be accessible when a VPN is
* active. Other hosts might only be accessible when the VPN is * active. Other hosts might only be accessible when the VPN is
* <emphasis>not</emphasis> active. Thus, it is best to use * not active. Thus, it is best to use g_network_monitor_can_reach()
* g_network_monitor_can_reach() or * or g_network_monitor_can_reach_async() to test for reachability
* g_network_monitor_can_reach_async() to test for reachability on a * on a host-by-host basis. (On the other hand, when the property is
* host-by-host basis. (On the other hand, when the property is
* %FALSE, the application can reasonably expect that no remote * %FALSE, the application can reasonably expect that no remote
* hosts at all are reachable, and should indicate this to the user * hosts at all are reachable, and should indicate this to the user
* in its UI.) * in its UI.)

26
gio/goutputstream.c
View File

@ -399,13 +399,12 @@ g_output_stream_vprintf (GOutputStream *stream,
* bindings or in other cases where the refcounted nature of #GBytes * bindings or in other cases where the refcounted nature of #GBytes
* is helpful over a bare pointer interface. * is helpful over a bare pointer interface.
* *
* However, note that this function <emphasis>may</emphasis> still * However, note that this function may still perform partial writes,
* perform partial writes, just like g_output_stream_write(). If that * just like g_output_stream_write(). If that occurs, to continue
* occurs, to continue writing, you will need to create a new #GBytes * writing, you will need to create a new #GBytes containing just the
* containing just the remaining bytes, using * remaining bytes, using g_bytes_new_from_bytes(). Passing the same
* g_bytes_new_from_bytes(). Passing the same #GBytes instance * #GBytes instance multiple times potentially can result in duplicated
* multiple times potentially can result in duplicated data in the * data in the output stream.
* output stream.
* *
* Return value: Number of bytes written, or -1 on error * Return value: Number of bytes written, or -1 on error
**/ **/
@ -897,13 +896,12 @@ write_bytes_callback (GObject *stream,
* takes a #GBytes as input. Due to the refcounted nature of #GBytes, * takes a #GBytes as input. Due to the refcounted nature of #GBytes,
* this allows the stream to avoid taking a copy of the data. * this allows the stream to avoid taking a copy of the data.
* *
* However, note that this function <emphasis>may</emphasis> still * However, note that this function may still perform partial writes,
* perform partial writes, just like g_output_stream_write_async(). * just like g_output_stream_write_async(). If that occurs, to continue
* If that occurs, to continue writing, you will need to create a new * writing, you will need to create a new #GBytes containing just the
* #GBytes containing just the remaining bytes, using * remaining bytes, using g_bytes_new_from_bytes(). Passing the same
* g_bytes_new_from_bytes(). Passing the same #GBytes instance * #GBytes instance multiple times potentially can result in duplicated
* multiple times potentially can result in duplicated data in the * data in the output stream.
* output stream.
* *
* For the synchronous, blocking version of this function, see * For the synchronous, blocking version of this function, see
* g_output_stream_write_bytes(). * g_output_stream_write_bytes().

5
gio/gresolver.c
View File

@ -595,9 +595,8 @@ g_resolver_get_service_rrname (const char *service,
* Synchronously performs a DNS SRV lookup for the given @service and * Synchronously performs a DNS SRV lookup for the given @service and
* @protocol in the given @domain and returns an array of #GSrvTarget. * @protocol in the given @domain and returns an array of #GSrvTarget.
* @domain may be an ASCII-only or UTF-8 hostname. Note also that the * @domain may be an ASCII-only or UTF-8 hostname. Note also that the
* @service and @protocol arguments <emphasis>do not</emphasis> * @service and @protocol arguments do not include the leading underscore
* include the leading underscore that appears in the actual DNS * that appears in the actual DNS entry.
* entry.
* *
* On success, g_resolver_lookup_service() will return a #GList of * On success, g_resolver_lookup_service() will return a #GList of
* #GSrvTarget, sorted in order of preference. (That is, you should * #GSrvTarget, sorted in order of preference. (That is, you should

3
gio/gsettings.c
View File

@ -2850,8 +2850,7 @@ g_settings_binding_writable_changed (GSettings *settings,
* *
* When the @inverted argument is %TRUE, the binding inverts the * When the @inverted argument is %TRUE, the binding inverts the
* value as it passes from the setting to the object, i.e. @property * value as it passes from the setting to the object, i.e. @property
* will be set to %TRUE if the key is <emphasis>not</emphasis> * will be set to %TRUE if the key is not writable.
* writable.
* *
* Note that the lifecycle of the binding is tied to the object, * Note that the lifecycle of the binding is tied to the object,
* and that you can have only one binding per object property. * and that you can have only one binding per object property.

4
gio/gtask.c
View File

@ -1190,8 +1190,8 @@ g_task_return (GTask *task,
* g_task_set_return_on_cancel() for more details. * g_task_set_return_on_cancel() for more details.
* *
* Other than in that case, @task will be completed when the * Other than in that case, @task will be completed when the
* #GTaskThreadFunc returns, <emphasis>not</emphasis> when it calls * #GTaskThreadFunc returns, not when it calls a
* a <literal>g_task_return_</literal> function. * <literal>g_task_return_</literal> function.
* *
* Since: 2.36 * Since: 2.36
*/ */

34
glib/docs.c
View File

@ -737,7 +737,7 @@
* p = (void*) 42; * p = (void*) 42;
* i = (int) p; * i = (int) p;
* ]| * ]|
* Again, that example was <emphasis>not</emphasis> correct, don't copy it. * Again, that example was not correct, don't copy it.
* The problem is that on some systems you need to do this: * The problem is that on some systems you need to do this:
* |[ * |[
* gpointer p; * gpointer p;
@ -761,9 +761,9 @@
* Stuffs an integer into a pointer type. * Stuffs an integer into a pointer type.
* *
* Remember, you may not store pointers in integers. This is not portable * Remember, you may not store pointers in integers. This is not portable
* in any way, shape or form. These macros <emphasis>only</emphasis> allow * in any way, shape or form. These macros only allow storing integers in
* storing integers in pointers, and only preserve 32 bits of the * pointers, and only preserve 32 bits of the integer; values outside the
* integer; values outside the range of a 32-bit integer will be mangled. * range of a 32-bit integer will be mangled.
*/ */
/** /**
@ -774,9 +774,9 @@
* been stored in the pointer with GINT_TO_POINTER(). * been stored in the pointer with GINT_TO_POINTER().
* *
* Remember, you may not store pointers in integers. This is not portable * Remember, you may not store pointers in integers. This is not portable
* in any way, shape or form. These macros <emphasis>only</emphasis> allow * in any way, shape or form. These macros only allow storing integers in
* storing integers in pointers, and only preserve 32 bits of the * pointers, and only preserve 32 bits of the integer; values outside the
* integer; values outside the range of a 32-bit integer will be mangled. * range of a 32-bit integer will be mangled.
*/ */
/** /**
@ -1679,19 +1679,17 @@
/** /**
* G_CONST_RETURN: * G_CONST_RETURN:
* *
* If <literal>G_DISABLE_CONST_RETURNS</literal> is defined, this macro expands * If %G_DISABLE_CONST_RETURNS is defined, this macro expands
* to nothing. By default, the macro expands to <literal>const</literal>. * to nothing. By default, the macro expands to const. The macro
* The macro should be used in place of <literal>const</literal> for * can be used in place of const for functions that return a value
* functions that return a value that should not be modified. The * that should not be modified. The purpose of this macro is to allow
* purpose of this macro is to allow us to turn on <literal>const</literal> * us to turn on const for returned constant strings by default, while
* for returned constant strings by default, while allowing programmers * allowing programmers who find that annoying to turn it off. This macro
* who find that annoying to turn it off. This macro should only be used * should only be used for return values and for "out" parameters, it
* for return values and for <emphasis>out</emphasis> parameters, it doesn't * doesn't make sense for "in" parameters.
* make sense for <emphasis>in</emphasis> parameters.
* *
* Deprecated: 2.30: API providers should replace all existing uses with * Deprecated: 2.30: API providers should replace all existing uses with
* <literal>const</literal> and API consumers should adjust their code * const and API consumers should adjust their code accordingly
* accordingly
*/ */
/** /**

2
glib/gcharset.c
View File

@ -438,7 +438,7 @@ append_locale_variants (GPtrArray *array,
* For example, if @locale is "fr_BE", then the returned list * For example, if @locale is "fr_BE", then the returned list
* is "fr_BE", "fr". * is "fr_BE", "fr".
* *
* If you need the list of variants for the <emphasis>current locale</emphasis>, * If you need the list of variants for the current locale,
* use g_get_language_names(). * use g_get_language_names().
* *
* Returns: (transfer full) (array zero-terminated=1) (element-type utf8): a newly * Returns: (transfer full) (array zero-terminated=1) (element-type utf8): a newly

17
glib/gconvert.c
View File

@ -98,12 +98,11 @@
* that use Glib do the same thing. If you get a file name from * that use Glib do the same thing. If you get a file name from
* the file system, for example, from readdir(3) or from g_dir_read_name(), * the file system, for example, from readdir(3) or from g_dir_read_name(),
* and you wish to display the file name to the user, you * and you wish to display the file name to the user, you
* <emphasis>will</emphasis> need to convert it into UTF-8. The * will need to convert it into UTF-8. The opposite case is when the
* opposite case is when the user types the name of a file he * user types the name of a file he wishes to save: the toolkit will
* wishes to save: the toolkit will give you that string in * give you that string in UTF-8 encoding, and you will need to convert
* UTF-8 encoding, and you will need to convert it to the * it to the character set used for file names before you can create the
* character set used for file names before you can create the * file with open() or fopen().
* file with open(2) or fopen(3).
* </para> * </para>
* <para> * <para>
* By default, Glib assumes that file names on disk are in UTF-8 * By default, Glib assumes that file names on disk are in UTF-8
@ -157,9 +156,9 @@
* <listitem><para> * <listitem><para>
* If you need to display a file name, convert it to UTF-8 first by * If you need to display a file name, convert it to UTF-8 first by
* using g_filename_to_utf8(). If conversion fails, display a string like * using g_filename_to_utf8(). If conversion fails, display a string like
* "<literal>Unknown file name</literal>". <emphasis>Do not</emphasis> * "Unknown file name". Do not convert this string back into the encoding
* convert this string back into the encoding used for file names if you * used for file names if you wish to pass it to the file system; use the
* wish to pass it to the file system; use the original file name instead. * original file name instead.
* For example, the document window of a word processor could display * For example, the document window of a word processor could display
* "Unknown file name" in its title bar but still let the user save the * "Unknown file name" in its title bar but still let the user save the
* file, as it would keep the raw file name internally. This can happen * file, as it would keep the raw file name internally. This can happen

24
glib/gdate.c
View File

@ -69,7 +69,7 @@
* or ISO timestamps or the like. It extrapolates the current Gregorian * or ISO timestamps or the like. It extrapolates the current Gregorian
* calendar forward and backward in time; there is no attempt to change * calendar forward and backward in time; there is no attempt to change
* the calendar to match time periods or locations. #GDate does not store * the calendar to match time periods or locations. #GDate does not store
* time information; it represents a <emphasis>day</emphasis>. * time information; it represents a day.
* *
* The #GDate implementation has several nice features; it is only a * The #GDate implementation has several nice features; it is only a
* 64-bit struct, so storing large numbers of dates is very efficient. It * 64-bit struct, so storing large numbers of dates is very efficient. It
@ -87,16 +87,16 @@
* calling g_date_clear(). A cleared date is sane; it's safe to call * calling g_date_clear(). A cleared date is sane; it's safe to call
* g_date_set_dmy() and the other mutator functions to initialize the * g_date_set_dmy() and the other mutator functions to initialize the
* value of a cleared date. However, a cleared date is initially * value of a cleared date. However, a cleared date is initially
* <emphasis>invalid</emphasis>, meaning that it doesn't represent a day * invalid, meaning that it doesn't represent a day that exists.
* that exists. It is undefined to call any of the date calculation * It is undefined to call any of the date calculation routines on an
* routines on an invalid date. If you obtain a date from a user or other * invalid date. If you obtain a date from a user or other
* unpredictable source, you should check its validity with the * unpredictable source, you should check its validity with the
* g_date_valid() predicate. g_date_valid() is also used to check for * g_date_valid() predicate. g_date_valid() is also used to check for
* errors with g_date_set_parse() and other functions that can * errors with g_date_set_parse() and other functions that can
* fail. Dates can be invalidated by calling g_date_clear() again. * fail. Dates can be invalidated by calling g_date_clear() again.
* *
* <emphasis>It is very important to use the API to access the #GDate * It is very important to use the API to access the #GDate
* struct.</emphasis> Often only the day-month-year or only the Julian * struct. Often only the day-month-year or only the Julian
* representation is valid. Sometimes neither is valid. Use the API. * representation is valid. Sometimes neither is valid. Use the API.
* *
* GLib also features #GDateTime which represents a precise time. * GLib also features #GDateTime which represents a precise time.
@ -151,11 +151,11 @@
* GTime: * GTime:
* *
* Simply a replacement for time_t. It has been deprecated * Simply a replacement for time_t. It has been deprecated
* since it is <emphasis>not</emphasis> equivalent to time_t * since it is not equivalent to time_t on 64-bit platforms
* on 64-bit platforms with a 64-bit time_t. Unrelated to #GTimer. * with a 64-bit time_t. Unrelated to #GTimer.
* *
* Note that #GTime is defined to always be a 32bit integer, * Note that #GTime is defined to always be a 32-bit integer,
* unlike time_t which may be 64bit on some systems. Therefore, * unlike time_t which may be 64-bit on some systems. Therefore,
* #GTime will overflow in the year 2038, and you cannot use the * #GTime will overflow in the year 2038, and you cannot use the
* address of a #GTime variable as argument to the UNIX time() * address of a #GTime variable as argument to the UNIX time()
* function. * function.
@ -183,8 +183,8 @@
/** /**
* GDateDay: * GDateDay:
* *
* Integer representing a day of the month; between 1 and * Integer representing a day of the month; between 1 and 31.
* 31. #G_DATE_BAD_DAY represents an invalid day of the month. * #G_DATE_BAD_DAY represents an invalid day of the month.
*/ */
/** /**

94
glib/gerror.c
View File

@ -30,18 +30,18 @@
* GLib provides a standard method of reporting errors from a called * GLib provides a standard method of reporting errors from a called
* function to the calling code. (This is the same problem solved by * function to the calling code. (This is the same problem solved by
* exceptions in other languages.) It's important to understand that * exceptions in other languages.) It's important to understand that
* this method is both a <emphasis>data type</emphasis> (the #GError * this method is both a data type (the #GError struct) and a set of
* object) and a <emphasis>set of rules.</emphasis> If you use #GError * rules. If you use #GError incorrectly, then your code will not
* incorrectly, then your code will not properly interoperate with other * properly interoperate with other code that uses #GError, and users
* code that uses #GError, and users of your API will probably get confused. * of your API will probably get confused.
* *
* First and foremost: <emphasis>#GError should only be used to report * First and foremost: #GError should only be used to report recoverable
* recoverable runtime errors, never to report programming * runtime errors, never to report programming errors. If the programmer
* errors.</emphasis> If the programmer has screwed up, then you should * has screwed up, then you should use g_warning(), g_return_if_fail(),
* use g_warning(), g_return_if_fail(), g_assert(), g_error(), or some * g_assert(), g_error(), or some similar facility. (Incidentally,
* similar facility. (Incidentally, remember that the g_error() function * remember that the g_error() function should only be used for
* should <emphasis>only</emphasis> be used for programming errors, it * programming errors, it should not be used to print any error
* should not be used to print any error reportable via #GError.) * reportable via #GError.)
* *
* Examples of recoverable runtime errors are "file not found" or * Examples of recoverable runtime errors are "file not found" or
* "failed to parse input." Examples of programming errors are "NULL * "failed to parse input." Examples of programming errors are "NULL
@ -81,14 +81,13 @@
* } * }
* ]| * ]|
* Note that <literal>err != NULL</literal> in this example is a * Note that <literal>err != NULL</literal> in this example is a
* <emphasis>reliable</emphasis> indicator of whether * reliable indicator of whether g_file_get_contents() failed.
* g_file_get_contents() failed. Additionally, g_file_get_contents() * Additionally, g_file_get_contents() returns a boolean which
* returns a boolean which indicates whether it was successful. * indicates whether it was successful.
* *
* Because g_file_get_contents() returns %FALSE on failure, if you * Because g_file_get_contents() returns %FALSE on failure, if you
* are only interested in whether it failed and don't need to display * are only interested in whether it failed and don't need to display
* an error message, you can pass %NULL for the <literal>error</literal> * an error message, you can pass %NULL for the @error argument:
* argument:
* |[ * |[
* if (g_file_get_contents ("foo.txt", &amp;contents, NULL, NULL)) /&ast; ignore errors &ast;/ * if (g_file_get_contents ("foo.txt", &amp;contents, NULL, NULL)) /&ast; ignore errors &ast;/
* /&ast; no error occurred &ast;/ ; * /&ast; no error occurred &ast;/ ;
@ -96,21 +95,19 @@
* /&ast; error &ast;/ ; * /&ast; error &ast;/ ;
* ]| * ]|
* *
* The #GError object contains three fields: <literal>domain</literal> * The #GError object contains three fields: @domain indicates the module
* indicates the module the error-reporting function is located in, * the error-reporting function is located in, @code indicates the specific
* <literal>code</literal> indicates the specific error that occurred, * error that occurred, and @message is a user-readable error message with
* and <literal>message</literal> is a user-readable error message with
* as many details as possible. Several functions are provided to deal * as many details as possible. Several functions are provided to deal
* with an error received from a called function: g_error_matches() * with an error received from a called function: g_error_matches()
* returns %TRUE if the error matches a given domain and code, * returns %TRUE if the error matches a given domain and code,
* g_propagate_error() copies an error into an error location (so the * g_propagate_error() copies an error into an error location (so the
* calling function will receive it), and g_clear_error() clears an * calling function will receive it), and g_clear_error() clears an
* error location by freeing the error and resetting the location to * error location by freeing the error and resetting the location to
* %NULL. To display an error to the user, simply display * %NULL. To display an error to the user, simply display the @message,
* <literal>error-&gt;message</literal>, perhaps along with additional * perhaps along with additional context known only to the calling
* context known only to the calling function (the file being opened, * function (the file being opened, or whatever - though in the
* or whatever -- though in the g_file_get_contents() case, * g_file_get_contents() case, the @message already contains a filename).
* <literal>error-&gt;message</literal> already contains a filename).
* *
* When implementing a function that can report errors, the basic * When implementing a function that can report errors, the basic
* tool is g_set_error(). Typically, if a fatal error occurs you * tool is g_set_error(). Typically, if a fatal error occurs you
@ -209,10 +206,10 @@
* } * }
* } * }
* ]| * ]|
* <literal>tmp_error</literal> should be checked immediately after * @tmp_error should be checked immediately after sub_function_that_can_fail(),
* sub_function_that_can_fail(), and either cleared or propagated * and either cleared or propagated upward. The rule is: after each error,
* upward. The rule is: <emphasis>after each error, you must either * you must either handle the error, or return it to the calling function.
* handle the error, or return it to the calling function</emphasis>. *
* Note that passing %NULL for the error location is the equivalent * Note that passing %NULL for the error location is the equivalent
* of handling an error by always doing nothing about it. So the * of handling an error by always doing nothing about it. So the
* following code is fine, assuming errors in sub_function_that_can_fail() * following code is fine, assuming errors in sub_function_that_can_fail()
@ -238,11 +235,11 @@
* } * }
* ]| * ]|
* *
* Note that passing %NULL for the error location * Note that passing %NULL for the error location ignores errors; it's
* <emphasis>ignores</emphasis> errors; it's equivalent to * equivalent to
* <literal>try { sub_function_that_can_fail (); } catch (...) {}</literal> * <literal>try { sub_function_that_can_fail (); } catch (...) {}</literal>
* in C++. It does <emphasis>not</emphasis> mean to leave errors * in C++. It does not mean to leave errors unhandled; it means to
* unhandled; it means to handle them by doing nothing. * handle them by doing nothing.
* *
* Error domains and codes are conventionally named as follows: * Error domains and codes are conventionally named as follows:
* <itemizedlist> * <itemizedlist>
@ -305,12 +302,11 @@
* not be affected by whether the caller wants to get a #GError. * not be affected by whether the caller wants to get a #GError.
* </para></listitem> * </para></listitem>
* <listitem><para> * <listitem><para>
* If a #GError is reported, then your function by definition * If a #GError is reported, then your function by definition had a
* <emphasis>had a fatal failure and did not complete whatever * fatal failure and did not complete whatever it was supposed to do.
* it was supposed to do</emphasis>. If the failure was not fatal, * If the failure was not fatal, then you handled it and you should not
* then you handled it and you should not report it. If it was fatal, * report it. If it was fatal, then you must report it and discontinue
* then you must report it and discontinue whatever you were doing * whatever you were doing immediately.
* immediately.
* </para></listitem> * </para></listitem>
* <listitem><para> * <listitem><para>
* If a #GError is reported, out parameters are not guaranteed to * If a #GError is reported, out parameters are not guaranteed to
@ -331,7 +327,7 @@
* <listitem><para> * <listitem><para>
* By convention, if you return a boolean value indicating success * By convention, if you return a boolean value indicating success
* then %TRUE means success and %FALSE means failure. If %FALSE is * then %TRUE means success and %FALSE means failure. If %FALSE is
* returned, the error <emphasis>must</emphasis> be set to a non-%NULL * returned, the error must be set to a non-%NULL
* value. * value.
* </para></listitem> * </para></listitem>
* <listitem><para> * <listitem><para>
@ -668,16 +664,13 @@ g_error_add_prefix (gchar **string,
* @format: printf()-style format string * @format: printf()-style format string
* @...: arguments to @format * @...: arguments to @format
* *
* Formats a string according to @format and * Formats a string according to @format and prefix it to an existing
* prefix it to an existing error message. If * error message. If @err is %NULL (ie: no error variable) then do
* @err is %NULL (ie: no error variable) then do
* nothing. * nothing.
* *
* If *@err is %NULL (ie: an error variable is * If *@err is %NULL (ie: an error variable is present but there is no
* present but there is no error condition) then * error condition) then also do nothing. Whether or not it makes sense
* also do nothing. Whether or not it makes * to take advantage of this feature is up to you.
* sense to take advantage of this feature is up
* to you.
* *
* Since: 2.16 * Since: 2.16
*/ */
@ -703,9 +696,8 @@ g_prefix_error (GError **err,
* @format: printf()-style format string * @format: printf()-style format string
* @...: arguments to @format * @...: arguments to @format
* *
* If @dest is %NULL, free @src; otherwise, * If @dest is %NULL, free @src; otherwise, moves @src into *@dest.
* moves @src into *@dest. *@dest must be %NULL. * *@dest must be %NULL. After the move, add a prefix as with
* After the move, add a prefix as with
* g_prefix_error(). * g_prefix_error().
* *
* Since: 2.16 * Since: 2.16

4
glib/ggettext.c
View File

@ -472,8 +472,8 @@ g_dngettext (const gchar *domain,
* *
* In order to use these macros in an application, you must include * In order to use these macros in an application, you must include
* <filename>glib/gi18n.h</filename>. For use in a library, you must include * <filename>glib/gi18n.h</filename>. For use in a library, you must include
* <filename>glib/gi18n-lib.h</filename> <emphasis>after</emphasis> defining * <filename>glib/gi18n-lib.h</filename> after defining the %GETTEXT_PACKAGE
* the GETTEXT_PACKAGE macro suitably for your library: * macro suitably for your library:
* |[ * |[
* &num;define GETTEXT_PACKAGE "gtk20" * &num;define GETTEXT_PACKAGE "gtk20"
* &num;include &lt;glib/gi18n-lib.h&gt; * &num;include &lt;glib/gi18n-lib.h&gt;

3
glib/giochannel.c
View File

@ -1317,8 +1317,7 @@ g_io_channel_get_buffered (GIOChannel *channel)
* %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. * %G_CONVERT_ERROR_ILLEGAL_SEQUENCE.
* Returning one of these statuses from g_io_channel_read_line(), * Returning one of these statuses from g_io_channel_read_line(),
* g_io_channel_read_line_string(), or g_io_channel_read_to_end() * g_io_channel_read_line_string(), or g_io_channel_read_to_end()
* does <emphasis>not</emphasis> guarantee that the encoding can * does not guarantee that the encoding can be changed.
* be changed.
* </para></listitem> * </para></listitem>
* </itemizedlist> * </itemizedlist>
* Channels which do not meet one of the above conditions cannot call * Channels which do not meet one of the above conditions cannot call

7
glib/gmain.c
View File

@ -688,10 +688,9 @@ static GPrivate thread_context_stack = G_PRIVATE_INIT (free_context_stack);
* started in this thread to run under @context and deliver their * started in this thread to run under @context and deliver their
* results to its main loop, rather than running under the global * results to its main loop, rather than running under the global
* default context in the main thread. Note that calling this function * default context in the main thread. Note that calling this function
* changes the context returned by * changes the context returned by g_main_context_get_thread_default(),
* g_main_context_get_thread_default(), <emphasis>not</emphasis> the * not the one returned by g_main_context_default(), so it does not affect
* one returned by g_main_context_default(), so it does not affect the * the context used by functions like g_idle_add().
* context used by functions like g_idle_add().
* *
* Normally you would call this function shortly after creating a new * Normally you would call this function shortly after creating a new
* thread, passing it a #GMainContext which will be run by a * thread, passing it a #GMainContext which will be run by a

18
glib/gmem.c
View File

@ -493,13 +493,17 @@ g_mem_is_system_malloc (void)
* g_mem_set_vtable: * g_mem_set_vtable:
* @vtable: table of memory allocation routines. * @vtable: table of memory allocation routines.
* *
* Sets the #GMemVTable to use for memory allocation. You can use this to provide * Sets the #GMemVTable to use for memory allocation. You can use this
* custom memory allocation routines. <emphasis>This function must be called * to provide custom memory allocation routines.
* before using any other GLib functions.</emphasis> The @vtable only needs to *
* provide malloc(), realloc(), and free() functions; GLib can provide default * The @vtable only needs to provide malloc(), realloc(), and free()
* implementations of the others. The malloc() and realloc() implementations * functions; GLib can provide default implementations of the others.
* should return %NULL on failure, GLib will handle error-checking for you. * The malloc() and realloc() implementations should return %NULL on
* @vtable is copied, so need not persist after this function has been called. * failure, GLib will handle error-checking for you. @vtable is copied,
* so need not persist after this function has been called.
*
* Note that this function must be called before using any other GLib
* functions.
*/ */
void void
g_mem_set_vtable (GMemVTable *vtable) g_mem_set_vtable (GMemVTable *vtable)

3
glib/gmessages.c
View File

@ -553,8 +553,7 @@ g_log_set_fatal_mask (const gchar *log_domain,
* </example> * </example>
* *
* <example> * <example>
* <title>Adding a log handler for <emphasis>all</emphasis> messages from * <title>Adding a log handler for all messages from GLib</title>
* GLib</title>
* <programlisting> * <programlisting>
* g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL * g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL
* | G_LOG_FLAG_RECURSION, my_log_handler, NULL); * | G_LOG_FLAG_RECURSION, my_log_handler, NULL);

6
glib/goption.c
View File

@ -2199,11 +2199,11 @@ g_option_group_new (const gchar *name,
* g_option_group_free: * g_option_group_free:
* @group: a #GOptionGroup * @group: a #GOptionGroup
* *
* Frees a #GOptionGroup. Note that you must <emphasis>not</emphasis> * Frees a #GOptionGroup. Note that you must not free groups
* free groups which have been added to a #GOptionContext. * which have been added to a #GOptionContext.
* *
* Since: 2.6 * Since: 2.6
**/ */
void void
g_option_group_free (GOptionGroup *group) g_option_group_free (GOptionGroup *group)
{ {

17
glib/gpattern.c
View File

@ -38,11 +38,9 @@
* semantics as the standard glob() function: '*' matches an arbitrary, * semantics as the standard glob() function: '*' matches an arbitrary,
* possibly empty, string, '?' matches an arbitrary character. * possibly empty, string, '?' matches an arbitrary character.
* *
* Note that in contrast to glob(), the '/' character * Note that in contrast to glob(), the '/' character can be matched by
* <emphasis>can</emphasis> be matched by the wildcards, there are no * the wildcards, there are no '[...]' character ranges and '*' and '?' can
* '[...]' character ranges and '*' and '?' can * not be escaped to include them literally in a pattern.
* <emphasis>not</emphasis> be escaped to include them literally in a
* pattern.
* *
* When multiple strings must be matched against the same pattern, it * When multiple strings must be matched against the same pattern, it
* is better to compile the pattern to a #GPatternSpec using * is better to compile the pattern to a #GPatternSpec using
@ -162,7 +160,7 @@ g_pattern_ph_match (const gchar *match_pattern,
* g_pattern_match: * g_pattern_match:
* @pspec: a #GPatternSpec * @pspec: a #GPatternSpec
* @string_length: the length of @string (in bytes, i.e. strlen(), * @string_length: the length of @string (in bytes, i.e. strlen(),
* <emphasis>not</emphasis> g_utf8_strlen()) * not g_utf8_strlen())
* @string: the UTF-8 encoded string to match * @string: the UTF-8 encoded string to match
* @string_reversed: (allow-none): the reverse of @string or %NULL * @string_reversed: (allow-none): the reverse of @string or %NULL
* *
@ -180,10 +178,9 @@ g_pattern_ph_match (const gchar *match_pattern,
* constructions thereof in the various calls to g_pattern_match(). * constructions thereof in the various calls to g_pattern_match().
* *
* Note also that the reverse of a UTF-8 encoded string can in general * Note also that the reverse of a UTF-8 encoded string can in general
* <emphasis>not</emphasis> be obtained by g_strreverse(). This works * not be obtained by g_strreverse(). This works only if the string
* only if the string doesn't contain any multibyte characters. GLib * does not contain any multibyte characters. GLib offers the
* offers the g_utf8_strreverse() function to reverse UTF-8 encoded * g_utf8_strreverse() function to reverse UTF-8 encoded strings.
* strings.
* *
* Returns: %TRUE if @string matches @pspec * Returns: %TRUE if @string matches @pspec
**/ **/

32
glib/gquark.c
View File

@ -82,14 +82,14 @@ static gint quark_block_offset = 0;
* representation for a string. One important advantage of interned * representation for a string. One important advantage of interned
* strings is that they can be compared for equality by a simple * strings is that they can be compared for equality by a simple
* pointer comparison, rather than using strcmp(). * pointer comparison, rather than using strcmp().
**/ */
/** /**
* GQuark: * GQuark:
* *
* A GQuark is a non-zero integer which uniquely identifies a * A GQuark is a non-zero integer which uniquely identifies a
* particular string. A GQuark value of zero is associated to %NULL. * particular string. A GQuark value of zero is associated to %NULL.
**/ */
/** /**
* G_DEFINE_QUARK: * G_DEFINE_QUARK:
@ -99,24 +99,26 @@ static gint quark_block_offset = 0;
* A convenience macro which defines a function returning the * A convenience macro which defines a function returning the
* #GQuark for the name @QN. The function will be named * #GQuark for the name @QN. The function will be named
* @q_n<!-- -->_quark(). * @q_n<!-- -->_quark().
* Note that the quark name will be stringified automatically in the *
* macro, so you shouldn't use double quotes. * Note that the quark name will be stringified automatically
* in the macro, so you shouldn't use double quotes.
* *
* Since: 2.34 * Since: 2.34
*/ */
/** /**
* g_quark_try_string: * g_quark_try_string:
* @string: (allow-none): a string. * @string: (allow-none): a string
* @Returns: the #GQuark associated with the string, or 0 if @string is
* %NULL or there is no #GQuark associated with it.
* *
* Gets the #GQuark associated with the given string, or 0 if string is * Gets the #GQuark associated with the given string, or 0 if string is
* %NULL or it has no associated #GQuark. * %NULL or it has no associated #GQuark.
* *
* If you want the GQuark to be created if it doesn't already exist, * If you want the GQuark to be created if it doesn't already exist,
* use g_quark_from_string() or g_quark_from_static_string(). * use g_quark_from_string() or g_quark_from_static_string().
**/ *
* Returns: the #GQuark associated with the string, or 0 if @string is
* %NULL or there is no #GQuark associated with it
*/
GQuark GQuark
g_quark_try_string (const gchar *string) g_quark_try_string (const gchar *string)
{ {
@ -182,14 +184,13 @@ quark_from_string (const gchar *string,
/** /**
* g_quark_from_string: * g_quark_from_string:
* @string: (allow-none): a string. * @string: (allow-none): a string
* *
* Gets the #GQuark identifying the given string. If the string does * Gets the #GQuark identifying the given string. If the string does
* not currently have an associated #GQuark, a new #GQuark is created, * not currently have an associated #GQuark, a new #GQuark is created,
* using a copy of the string. * using a copy of the string.
* *
* Returns: the #GQuark identifying the string, or 0 if @string is * Returns: the #GQuark identifying the string, or 0 if @string is %NULL
* %NULL.
*/ */
GQuark GQuark
g_quark_from_string (const gchar *string) g_quark_from_string (const gchar *string)
@ -208,7 +209,7 @@ g_quark_from_string (const gchar *string)
/** /**
* g_quark_from_static_string: * g_quark_from_static_string:
* @string: (allow-none): a string. * @string: (allow-none): a string
* *
* Gets the #GQuark identifying the given (static) string. If the * Gets the #GQuark identifying the given (static) string. If the
* string does not currently have an associated #GQuark, a new #GQuark * string does not currently have an associated #GQuark, a new #GQuark
@ -217,14 +218,13 @@ g_quark_from_string (const gchar *string)
* Note that this function is identical to g_quark_from_string() except * Note that this function is identical to g_quark_from_string() except
* that if a new #GQuark is created the string itself is used rather * that if a new #GQuark is created the string itself is used rather
* than a copy. This saves memory, but can only be used if the string * than a copy. This saves memory, but can only be used if the string
* will <emphasis>always</emphasis> exist. It can be used with * will continue to exist until the program terminates. It can be used
* statically allocated strings in the main program, but not with * with statically allocated strings in the main program, but not with
* statically allocated memory in dynamically loaded modules, if you * statically allocated memory in dynamically loaded modules, if you
* expect to ever unload the module again (e.g. do not use this * expect to ever unload the module again (e.g. do not use this
* function in GTK+ theme engines). * function in GTK+ theme engines).
* *
* Returns: the #GQuark identifying the string, or 0 if @string is * Returns: the #GQuark identifying the string, or 0 if @string is %NULL
* %NULL.
*/ */
GQuark GQuark
g_quark_from_static_string (const gchar *string) g_quark_from_static_string (const gchar *string)

18
glib/gqueue.c
View File

@ -375,8 +375,7 @@ g_queue_push_nth (GQueue *queue,
/** /**
* g_queue_push_head_link: * g_queue_push_head_link:
* @queue: a #GQueue * @queue: a #GQueue
* @link_: a single #GList element, <emphasis>not</emphasis> a list with * @link_: a single #GList element, not a list with more than one element
* more than one element
* *
* Adds a new element at the head of the queue. * Adds a new element at the head of the queue.
*/ */
@ -422,8 +421,7 @@ g_queue_push_tail (GQueue *queue,
/** /**
* g_queue_push_tail_link: * g_queue_push_tail_link:
* @queue: a #GQueue * @queue: a #GQueue
* @link_: a single #GList element, <emphasis>not</emphasis> a list with * @link_: a single #GList element, not a list with more than one element
* more than one element
* *
* Adds a new element at the tail of the queue. * Adds a new element at the tail of the queue.
*/ */
@ -791,10 +789,10 @@ g_queue_link_index (GQueue *queue,
/** /**
* g_queue_unlink: * g_queue_unlink:
* @queue: a #GQueue * @queue: a #GQueue
* @link_: a #GList link that <emphasis>must</emphasis> be part of @queue * @link_: a #GList link that must be part of @queue
* *
* Unlinks @link_ so that it will no longer be part of @queue. The link is * Unlinks @link_ so that it will no longer be part of @queue.
* not freed. * The link is not freed.
* *
* @link_ must be part of @queue. * @link_ must be part of @queue.
* *
@ -817,7 +815,7 @@ g_queue_unlink (GQueue *queue,
/** /**
* g_queue_delete_link: * g_queue_delete_link:
* @queue: a #GQueue * @queue: a #GQueue
* @link_: a #GList link that <emphasis>must</emphasis> be part of @queue * @link_: a #GList link that must be part of @queue
* *
* Removes @link_ from @queue and frees it. * Removes @link_ from @queue and frees it.
* *
@ -985,7 +983,7 @@ g_queue_remove_all (GQueue *queue,
/** /**
* g_queue_insert_before: * g_queue_insert_before:
* @queue: a #GQueue * @queue: a #GQueue
* @sibling: a #GList link that <emphasis>must</emphasis> be part of @queue * @sibling: a #GList link that must be part of @queue
* @data: the data to insert * @data: the data to insert
* *
* Inserts @data into @queue before @sibling. * Inserts @data into @queue before @sibling.
@ -1009,7 +1007,7 @@ g_queue_insert_before (GQueue *queue,
/** /**
* g_queue_insert_after: * g_queue_insert_after:
* @queue: a #GQueue * @queue: a #GQueue
* @sibling: a #GList link that <emphasis>must</emphasis> be part of @queue * @sibling: a #GList link that must be part of @queue
* @data: the data to insert * @data: the data to insert
* *
* Inserts @data into @queue after @sibling * Inserts @data into @queue after @sibling

137
glib/gsequence.c
View File

@ -63,14 +63,14 @@
* g_sequence_move_range() will not invalidate the iterators pointing * g_sequence_move_range() will not invalidate the iterators pointing
* to it. The only operation that will invalidate an iterator is when * to it. The only operation that will invalidate an iterator is when
* the element it points to is removed from any sequence. * the element it points to is removed from any sequence.
**/ */
/** /**
* GSequenceIter: * GSequenceIter:
* *
* The #GSequenceIter struct is an opaque data type representing an * The #GSequenceIter struct is an opaque data type representing an
* iterator pointing into a #GSequence. * iterator pointing into a #GSequence.
**/ */
/** /**
* GSequenceIterCompareFunc: * GSequenceIterCompareFunc:
@ -83,9 +83,8 @@
* if @a comes before @b, and a positive value if @b comes before @a. * if @a comes before @b, and a positive value if @b comes before @a.
* *
* Returns: zero if the iterators are equal, a negative value if @a * Returns: zero if the iterators are equal, a negative value if @a
* comes before @b, and a positive value if @b comes before * comes before @b, and a positive value if @b comes before @a.
* @a. */
**/
typedef struct _GSequenceNode GSequenceNode; typedef struct _GSequenceNode GSequenceNode;
@ -94,7 +93,7 @@ typedef struct _GSequenceNode GSequenceNode;
* *
* The #GSequence struct is an opaque data type representing a * The #GSequence struct is an opaque data type representing a
* <link linkend="glib-Sequences">Sequence</link> data type. * <link linkend="glib-Sequences">Sequence</link> data type.
**/ */
struct _GSequence struct _GSequence
{ {
GSequenceNode * end_node; GSequenceNode * end_node;
@ -268,11 +267,11 @@ g_sequence_new (GDestroyNotify data_destroy)
* @seq: a #GSequence * @seq: a #GSequence
* *
* Frees the memory allocated for @seq. If @seq has a data destroy * Frees the memory allocated for @seq. If @seq has a data destroy
* function associated with it, that function is called on all items in * function associated with it, that function is called on all items
* @seq. * in @seq.
* *
* Since: 2.14 * Since: 2.14
**/ */
void void
g_sequence_free (GSequence *seq) g_sequence_free (GSequence *seq)
{ {
@ -296,7 +295,7 @@ g_sequence_free (GSequence *seq)
* @user_data to the function. * @user_data to the function.
* *
* Since: 2.14 * Since: 2.14
**/ */
void void
g_sequence_foreach_range (GSequenceIter *begin, g_sequence_foreach_range (GSequenceIter *begin,
GSequenceIter *end, GSequenceIter *end,
@ -337,7 +336,7 @@ g_sequence_foreach_range (GSequenceIter *begin,
* to the function. * to the function.
* *
* Since: 2.14 * Since: 2.14
**/ */
void void
g_sequence_foreach (GSequence *seq, g_sequence_foreach (GSequence *seq,
GFunc func, GFunc func,
@ -360,16 +359,16 @@ g_sequence_foreach (GSequence *seq,
* *
* Finds an iterator somewhere in the range (@begin, @end). This * Finds an iterator somewhere in the range (@begin, @end). This
* iterator will be close to the middle of the range, but is not * iterator will be close to the middle of the range, but is not
* guaranteed to be <emphasis>exactly</emphasis> in the middle. * guaranteed to be exactly in the middle.
* *
* The @begin and @end iterators must both point to the same sequence and * The @begin and @end iterators must both point to the same sequence
* @begin must come before or be equal to @end in the sequence. * and @begin must come before or be equal to @end in the sequence.
* *
* Return value: A #GSequenceIter pointing somewhere in the * Return value: a #GSequenceIter pointing somewhere in the
* (@begin, @end) range. * (@begin, @end) range
* *
* Since: 2.14 * Since: 2.14
**/ */
GSequenceIter * GSequenceIter *
g_sequence_range_get_midpoint (GSequenceIter *begin, g_sequence_range_get_midpoint (GSequenceIter *begin,
GSequenceIter *end) GSequenceIter *end)
@ -400,11 +399,11 @@ g_sequence_range_get_midpoint (GSequenceIter *begin,
* *
* The @a and @b iterators must point into the same sequence. * The @a and @b iterators must point into the same sequence.
* *
* Return value: A negative number if @a comes before @b, 0 if they are * Return value: a negative number if @a comes before @b, 0 if they are
* equal, and a positive number if @a comes after @b. * equal, and a positive number if @a comes after @b
* *
* Since: 2.14 * Since: 2.14
**/ */
gint gint
g_sequence_iter_compare (GSequenceIter *a, g_sequence_iter_compare (GSequenceIter *a,
GSequenceIter *b) GSequenceIter *b)
@ -439,7 +438,7 @@ g_sequence_iter_compare (GSequenceIter *a,
* Return value: an iterator pointing to the new item * Return value: an iterator pointing to the new item
* *
* Since: 2.14 * Since: 2.14
**/ */
GSequenceIter * GSequenceIter *
g_sequence_append (GSequence *seq, g_sequence_append (GSequence *seq,
gpointer data) gpointer data)
@ -466,7 +465,7 @@ g_sequence_append (GSequence *seq,
* Return value: an iterator pointing to the new item * Return value: an iterator pointing to the new item
* *
* Since: 2.14 * Since: 2.14
**/ */
GSequenceIter * GSequenceIter *
g_sequence_prepend (GSequence *seq, g_sequence_prepend (GSequence *seq,
gpointer data) gpointer data)
@ -495,7 +494,7 @@ g_sequence_prepend (GSequence *seq,
* Return value: an iterator pointing to the new item * Return value: an iterator pointing to the new item
* *
* Since: 2.14 * Since: 2.14
**/ */
GSequenceIter * GSequenceIter *
g_sequence_insert_before (GSequenceIter *iter, g_sequence_insert_before (GSequenceIter *iter,
gpointer data) gpointer data)
@ -524,7 +523,7 @@ g_sequence_insert_before (GSequenceIter *iter,
* function is called on the data for the removed item. * function is called on the data for the removed item.
* *
* Since: 2.14 * Since: 2.14
**/ */
void void
g_sequence_remove (GSequenceIter *iter) g_sequence_remove (GSequenceIter *iter)
{ {
@ -552,7 +551,7 @@ g_sequence_remove (GSequenceIter *iter)
* function is called on the data for the removed items. * function is called on the data for the removed items.
* *
* Since: 2.14 * Since: 2.14
**/ */
void void
g_sequence_remove_range (GSequenceIter *begin, g_sequence_remove_range (GSequenceIter *begin,
GSequenceIter *end) GSequenceIter *end)
@ -581,7 +580,7 @@ g_sequence_remove_range (GSequenceIter *begin,
* the (@begin, @end) range, the range does not move. * the (@begin, @end) range, the range does not move.
* *
* Since: 2.14 * Since: 2.14
**/ */
void void
g_sequence_move_range (GSequenceIter *dest, g_sequence_move_range (GSequenceIter *dest,
GSequenceIter *begin, GSequenceIter *begin,
@ -660,7 +659,7 @@ g_sequence_move_range (GSequenceIter *dest,
* if the second comes before the first. * if the second comes before the first.
* *
* Since: 2.14 * Since: 2.14
**/ */
void void
g_sequence_sort (GSequence *seq, g_sequence_sort (GSequence *seq,
GCompareDataFunc cmp_func, GCompareDataFunc cmp_func,
@ -696,7 +695,7 @@ g_sequence_sort (GSequence *seq,
* Return value: a #GSequenceIter pointing to the new item. * Return value: a #GSequenceIter pointing to the new item.
* *
* Since: 2.14 * Since: 2.14
**/ */
GSequenceIter * GSequenceIter *
g_sequence_insert_sorted (GSequence *seq, g_sequence_insert_sorted (GSequence *seq,
gpointer data, gpointer data,
@ -733,7 +732,7 @@ g_sequence_insert_sorted (GSequence *seq,
* the second item comes before the first. * the second item comes before the first.
* *
* Since: 2.14 * Since: 2.14
**/ */
void void
g_sequence_sort_changed (GSequenceIter *iter, g_sequence_sort_changed (GSequenceIter *iter,
GCompareDataFunc cmp_func, GCompareDataFunc cmp_func,
@ -756,7 +755,7 @@ g_sequence_sort_changed (GSequenceIter *iter,
* @seq: a #GSequence * @seq: a #GSequence
* @data: data for the new item * @data: data for the new item
* @cmp_func: the function used to compare items in the sequence * @cmp_func: the function used to compare items in the sequence
* @cmp_data: user data passed to @cmp_func. * @cmp_data: user data passed to @cmp_func
* *
* Returns an iterator pointing to the position where @data would * Returns an iterator pointing to the position where @data would
* be inserted according to @cmp_func and @cmp_data. * be inserted according to @cmp_func and @cmp_data.
@ -776,10 +775,10 @@ g_sequence_sort_changed (GSequenceIter *iter,
* doing unsorted insertions. * doing unsorted insertions.
* *
* Return value: an #GSequenceIter pointing to the position where @data * Return value: an #GSequenceIter pointing to the position where @data
* would have been inserted according to @cmp_func and @cmp_data. * would have been inserted according to @cmp_func and @cmp_data
* *
* Since: 2.14 * Since: 2.14
**/ */
GSequenceIter * GSequenceIter *
g_sequence_search (GSequence *seq, g_sequence_search (GSequence *seq,
gpointer data, gpointer data,
@ -803,7 +802,7 @@ g_sequence_search (GSequence *seq,
* @seq: a #GSequence * @seq: a #GSequence
* @data: data to lookup * @data: data to lookup
* @cmp_func: the function used to compare items in the sequence * @cmp_func: the function used to compare items in the sequence
* @cmp_data: user data passed to @cmp_func. * @cmp_data: user data passed to @cmp_func
* *
* Returns an iterator pointing to the position of the first item found * Returns an iterator pointing to the position of the first item found
* equal to @data according to @cmp_func and @cmp_data. If more than one * equal to @data according to @cmp_func and @cmp_data. If more than one
@ -824,10 +823,10 @@ g_sequence_search (GSequence *seq,
* *
* Return value: an #GSequenceIter pointing to the position of the * Return value: an #GSequenceIter pointing to the position of the
* first item found equal to @data according to @cmp_func and * first item found equal to @data according to @cmp_func and
* @cmp_data, or %NULL if no such item exists. * @cmp_data, or %NULL if no such item exists
* *
* Since: 2.28 * Since: 2.28
**/ */
GSequenceIter * GSequenceIter *
g_sequence_lookup (GSequence *seq, g_sequence_lookup (GSequence *seq,
gpointer data, gpointer data,
@ -861,7 +860,7 @@ g_sequence_lookup (GSequence *seq,
* iterator comes before the first. * iterator comes before the first.
* *
* Since: 2.14 * Since: 2.14
**/ */
void void
g_sequence_sort_iter (GSequence *seq, g_sequence_sort_iter (GSequence *seq,
GSequenceIterCompareFunc cmp_func, GSequenceIterCompareFunc cmp_func,
@ -916,7 +915,7 @@ g_sequence_sort_iter (GSequence *seq,
* iterator comes before the first. * iterator comes before the first.
* *
* Since: 2.14 * Since: 2.14
**/ */
void void
g_sequence_sort_changed_iter (GSequenceIter *iter, g_sequence_sort_changed_iter (GSequenceIter *iter,
GSequenceIterCompareFunc iter_cmp, GSequenceIterCompareFunc iter_cmp,
@ -986,7 +985,7 @@ g_sequence_sort_changed_iter (GSequenceIter *iter,
* Return value: a #GSequenceIter pointing to the new item * Return value: a #GSequenceIter pointing to the new item
* *
* Since: 2.14 * Since: 2.14
**/ */
GSequenceIter * GSequenceIter *
g_sequence_insert_sorted_iter (GSequence *seq, g_sequence_insert_sorted_iter (GSequence *seq,
gpointer data, gpointer data,
@ -1056,10 +1055,10 @@ g_sequence_insert_sorted_iter (GSequence *seq,
* *
* Return value: a #GSequenceIter pointing to the position in @seq * Return value: a #GSequenceIter pointing to the position in @seq
* where @data would have been inserted according to @iter_cmp * where @data would have been inserted according to @iter_cmp
* and @cmp_data. * and @cmp_data
* *
* Since: 2.14 * Since: 2.14
**/ */
GSequenceIter * GSequenceIter *
g_sequence_search_iter (GSequence *seq, g_sequence_search_iter (GSequence *seq,
gpointer data, gpointer data,
@ -1114,10 +1113,10 @@ g_sequence_search_iter (GSequence *seq,
* *
* Return value: an #GSequenceIter pointing to the position of * Return value: an #GSequenceIter pointing to the position of
* the first item found equal to @data according to @cmp_func * the first item found equal to @data according to @cmp_func
* and @cmp_data, or %NULL if no such item exists. * and @cmp_data, or %NULL if no such item exists
* *
* Since: 2.28 * Since: 2.28
**/ */
GSequenceIter * GSequenceIter *
g_sequence_lookup_iter (GSequence *seq, g_sequence_lookup_iter (GSequence *seq,
gpointer data, gpointer data,
@ -1155,10 +1154,10 @@ g_sequence_lookup_iter (GSequence *seq,
* *
* Returns the #GSequence that @iter points into. * Returns the #GSequence that @iter points into.
* *
* Return value: the #GSequence that @iter points into. * Return value: the #GSequence that @iter points into
* *
* Since: 2.14 * Since: 2.14
**/ */
GSequence * GSequence *
g_sequence_iter_get_sequence (GSequenceIter *iter) g_sequence_iter_get_sequence (GSequenceIter *iter)
{ {
@ -1183,7 +1182,7 @@ g_sequence_iter_get_sequence (GSequenceIter *iter)
* Return value: the data that @iter points to * Return value: the data that @iter points to
* *
* Since: 2.14 * Since: 2.14
**/ */
gpointer gpointer
g_sequence_get (GSequenceIter *iter) g_sequence_get (GSequenceIter *iter)
{ {
@ -1203,7 +1202,7 @@ g_sequence_get (GSequenceIter *iter)
* function is called on the existing data that @iter pointed to. * function is called on the existing data that @iter pointed to.
* *
* Since: 2.14 * Since: 2.14
**/ */
void void
g_sequence_set (GSequenceIter *iter, g_sequence_set (GSequenceIter *iter,
gpointer data) gpointer data)
@ -1239,7 +1238,7 @@ g_sequence_set (GSequenceIter *iter,
* Return value: the length of @seq * Return value: the length of @seq
* *
* Since: 2.14 * Since: 2.14
**/ */
gint gint
g_sequence_get_length (GSequence *seq) g_sequence_get_length (GSequence *seq)
{ {
@ -1255,7 +1254,7 @@ g_sequence_get_length (GSequence *seq)
* Return value: the end iterator for @seq * Return value: the end iterator for @seq
* *
* Since: 2.14 * Since: 2.14
**/ */
GSequenceIter * GSequenceIter *
g_sequence_get_end_iter (GSequence *seq) g_sequence_get_end_iter (GSequence *seq)
{ {
@ -1273,7 +1272,7 @@ g_sequence_get_end_iter (GSequence *seq)
* Return value: the begin iterator for @seq. * Return value: the begin iterator for @seq.
* *
* Since: 2.14 * Since: 2.14
**/ */
GSequenceIter * GSequenceIter *
g_sequence_get_begin_iter (GSequence *seq) g_sequence_get_begin_iter (GSequence *seq)
{ {
@ -1300,7 +1299,7 @@ clamp_position (GSequence *seq,
/** /**
* g_sequence_get_iter_at_pos: * g_sequence_get_iter_at_pos:
* @seq: a #GSequence * @seq: a #GSequence
* @pos: a position in @seq, or -1 for the end. * @pos: a position in @seq, or -1 for the end
* *
* Returns the iterator at position @pos. If @pos is negative or larger * Returns the iterator at position @pos. If @pos is negative or larger
* than the number of items in @seq, the end iterator is returned. * than the number of items in @seq, the end iterator is returned.
@ -1308,7 +1307,7 @@ clamp_position (GSequence *seq,
* Return value: The #GSequenceIter at position @pos * Return value: The #GSequenceIter at position @pos
* *
* Since: 2.14 * Since: 2.14
**/ */
GSequenceIter * GSequenceIter *
g_sequence_get_iter_at_pos (GSequence *seq, g_sequence_get_iter_at_pos (GSequence *seq,
gint pos) gint pos)
@ -1324,7 +1323,7 @@ g_sequence_get_iter_at_pos (GSequence *seq,
* g_sequence_move: * g_sequence_move:
* @src: a #GSequenceIter pointing to the item to move * @src: a #GSequenceIter pointing to the item to move
* @dest: a #GSequenceIter pointing to the position to which * @dest: a #GSequenceIter pointing to the position to which
* the item is moved. * the item is moved
* *
* Moves the item pointed to by @src to the position indicated by @dest. * Moves the item pointed to by @src to the position indicated by @dest.
* After calling this function @dest will point to the position immediately * After calling this function @dest will point to the position immediately
@ -1356,10 +1355,10 @@ g_sequence_move (GSequenceIter *src,
* *
* Returns whether @iter is the end iterator * Returns whether @iter is the end iterator
* *
* Return value: Whether @iter is the end iterator. * Return value: Whether @iter is the end iterator
* *
* Since: 2.14 * Since: 2.14
**/ */
gboolean gboolean
g_sequence_iter_is_end (GSequenceIter *iter) g_sequence_iter_is_end (GSequenceIter *iter)
{ {
@ -1377,7 +1376,7 @@ g_sequence_iter_is_end (GSequenceIter *iter)
* Return value: whether @iter is the begin iterator * Return value: whether @iter is the begin iterator
* *
* Since: 2.14 * Since: 2.14
**/ */
gboolean gboolean
g_sequence_iter_is_begin (GSequenceIter *iter) g_sequence_iter_is_begin (GSequenceIter *iter)
{ {
@ -1395,7 +1394,7 @@ g_sequence_iter_is_begin (GSequenceIter *iter)
* Return value: the position of @iter * Return value: the position of @iter
* *
* Since: 2.14 * Since: 2.14
**/ */
gint gint
g_sequence_iter_get_position (GSequenceIter *iter) g_sequence_iter_get_position (GSequenceIter *iter)
{ {
@ -1408,13 +1407,13 @@ g_sequence_iter_get_position (GSequenceIter *iter)
* g_sequence_iter_next: * g_sequence_iter_next:
* @iter: a #GSequenceIter * @iter: a #GSequenceIter
* *
* Returns an iterator pointing to the next position after @iter. If * Returns an iterator pointing to the next position after @iter.
* @iter is the end iterator, the end iterator is returned. * If @iter is the end iterator, the end iterator is returned.
* *
* Return value: a #GSequenceIter pointing to the next position after @iter. * Return value: a #GSequenceIter pointing to the next position after @iter
* *
* Since: 2.14 * Since: 2.14
**/ */
GSequenceIter * GSequenceIter *
g_sequence_iter_next (GSequenceIter *iter) g_sequence_iter_next (GSequenceIter *iter)
{ {
@ -1427,14 +1426,14 @@ g_sequence_iter_next (GSequenceIter *iter)
* g_sequence_iter_prev: * g_sequence_iter_prev:
* @iter: a #GSequenceIter * @iter: a #GSequenceIter
* *
* Returns an iterator pointing to the previous position before @iter. If * Returns an iterator pointing to the previous position before @iter.
* @iter is the begin iterator, the begin iterator is returned. * If @iter is the begin iterator, the begin iterator is returned.
* *
* Return value: a #GSequenceIter pointing to the previous position before * Return value: a #GSequenceIter pointing to the previous position
* @iter. * before @iter
* *
* Since: 2.14 * Since: 2.14
**/ */
GSequenceIter * GSequenceIter *
g_sequence_iter_prev (GSequenceIter *iter) g_sequence_iter_prev (GSequenceIter *iter)
{ {
@ -1447,17 +1446,17 @@ g_sequence_iter_prev (GSequenceIter *iter)
* g_sequence_iter_move: * g_sequence_iter_move:
* @iter: a #GSequenceIter * @iter: a #GSequenceIter
* @delta: A positive or negative number indicating how many positions away * @delta: A positive or negative number indicating how many positions away
* from @iter the returned #GSequenceIter will be. * from @iter the returned #GSequenceIter will be
* *
* Returns the #GSequenceIter which is @delta positions away from @iter. * Returns the #GSequenceIter which is @delta positions away from @iter.
* If @iter is closer than -@delta positions to the beginning of the sequence, * If @iter is closer than -@delta positions to the beginning of the sequence,
* the begin iterator is returned. If @iter is closer than @delta positions * the begin iterator is returned. If @iter is closer than @delta positions
* to the end of the sequence, the end iterator is returned. * to the end of the sequence, the end iterator is returned.
* *
* Return value: a #GSequenceIter which is @delta positions away from @iter. * Return value: a #GSequenceIter which is @delta positions away from @iter
* *
* Since: 2.14 * Since: 2.14
**/ */
GSequenceIter * GSequenceIter *
g_sequence_iter_move (GSequenceIter *iter, g_sequence_iter_move (GSequenceIter *iter,
gint delta) gint delta)
@ -1488,7 +1487,7 @@ g_sequence_iter_move (GSequenceIter *iter,
* to point into difference sequences. * to point into difference sequences.
* *
* Since: 2.14 * Since: 2.14
**/ */
void void
g_sequence_swap (GSequenceIter *a, g_sequence_swap (GSequenceIter *a,
GSequenceIter *b) GSequenceIter *b)

30
glib/gstrfuncs.c
View File

@ -66,7 +66,7 @@
* Note that the functions g_printf(), g_fprintf(), g_sprintf(), * Note that the functions g_printf(), g_fprintf(), g_sprintf(),
* g_snprintf(), g_vprintf(), g_vfprintf(), g_vsprintf() and g_vsnprintf() * g_snprintf(), g_vprintf(), g_vfprintf(), g_vsprintf() and g_vsnprintf()
* are declared in the header <filename>gprintf.h</filename> which is * are declared in the header <filename>gprintf.h</filename> which is
* <emphasis>not</emphasis> included in <filename>glib.h</filename> * not included in <filename>glib.h</filename>
* (otherwise using <filename>glib.h</filename> would drag in * (otherwise using <filename>glib.h</filename> would drag in
* <filename>stdio.h</filename>), so you'll have to explicitly include * <filename>stdio.h</filename>), so you'll have to explicitly include
* <literal>&lt;glib/gprintf.h&gt;</literal> in order to use the GLib * <literal>&lt;glib/gprintf.h&gt;</literal> in order to use the GLib
@ -75,14 +75,14 @@
* <para id="string-precision">While you may use the printf() functions * <para id="string-precision">While you may use the printf() functions
* to format UTF-8 strings, notice that the precision of a * to format UTF-8 strings, notice that the precision of a
* <literal>&percnt;Ns</literal> parameter is interpreted as the * <literal>&percnt;Ns</literal> parameter is interpreted as the
* number of <emphasis>bytes</emphasis>, not <emphasis>characters</emphasis> * number of bytes, not characters to print. On top of that, the GNU
* to print. On top of that, the GNU libc implementation of the printf() * libc implementation of the printf() functions has the "feature" that
* functions has the "feature" that it checks that the string given for * it checks that the string given for the <literal>&percnt;Ns</literal>
* the <literal>&percnt;Ns</literal> parameter consists of a whole number * parameter consists of a whole number of characters in the current
* of characters in the current encoding. So, unless you are sure you are * encoding. So, unless you are sure you are always going to be in an
* always going to be in an UTF-8 locale or your know your text is restricted * UTF-8 locale or your know your text is restricted to ASCII, avoid
* to ASCII, avoid using <literal>&percnt;Ns</literal>. If your intention is * using <literal>&percnt;Ns</literal>. If your intention is to format
* to format strings for a certain number of columns, then * strings for a certain number of columns, then
* <literal>&percnt;Ns</literal> is not a correct solution anyway, since it * <literal>&percnt;Ns</literal> is not a correct solution anyway, since it
* fails to take wide characters (see g_unichar_iswide()) into account. * fails to take wide characters (see g_unichar_iswide()) into account.
* </para> * </para>
@ -1332,13 +1332,13 @@ g_strlcat (gchar *dest,
* Portability wrapper that calls strlcpy() on systems which have it, * Portability wrapper that calls strlcpy() on systems which have it,
* and emulates strlcpy() otherwise. Copies @src to @dest; @dest is * and emulates strlcpy() otherwise. Copies @src to @dest; @dest is
* guaranteed to be nul-terminated; @src must be nul-terminated; * guaranteed to be nul-terminated; @src must be nul-terminated;
* @dest_size is the buffer size, not the number of chars to copy. * @dest_size is the buffer size, not the number of bytes to copy.
* *
* At most dest_size - 1 characters will be copied. Always nul-terminates * At most @dest_size - 1 characters will be copied. Always nul-terminates
* (unless dest_size == 0). This function does <emphasis>not</emphasis> * (unless @dest_size is 0). This function does not allocate memory. Unlike
* allocate memory. Unlike strncpy(), this function doesn't pad dest (so * strncpy(), this function doesn't pad @dest (so it's often faster). It
* it's often faster). It returns the size of the attempted result, * returns the size of the attempted result, strlen (src), so if
* strlen (src), so if @retval >= @dest_size, truncation occurred. * @retval >= @dest_size, truncation occurred.
* *
* Caveat: strlcpy() is supposedly more secure than strcpy() or strncpy(), * Caveat: strlcpy() is supposedly more secure than strcpy() or strncpy(),
* but if you really want to avoid screwups, g_strdup() is an even better * but if you really want to avoid screwups, g_strdup() is an even better

7
glib/gthread.c
View File

@ -144,10 +144,9 @@
* not automatically locked for performance reasons. For example, * not automatically locked for performance reasons. For example,
* you must coordinate accesses to the same #GHashTable from multiple * you must coordinate accesses to the same #GHashTable from multiple
* threads. The two notable exceptions from this rule are #GMainLoop * threads. The two notable exceptions from this rule are #GMainLoop
* and #GAsyncQueue, which <emphasis>are</emphasis> thread-safe and * and #GAsyncQueue, which are thread-safe and need no further
* need no further application-level locking to be accessed from * application-level locking to be accessed from multiple threads.
* multiple threads. Most refcounting functions such as g_object_ref() * Most refcounting functions such as g_object_ref() are also thread-safe.
* are also thread-safe.
*/ */
/* G_LOCK Documentation {{{1 ---------------------------------------------- */ /* G_LOCK Documentation {{{1 ---------------------------------------------- */

8
glib/gutf8.c
View File

@ -1608,12 +1608,12 @@ fast_validate_len (const char *str,
* being validated otherwise). * being validated otherwise).
* *
* Note that g_utf8_validate() returns %FALSE if @max_len is * Note that g_utf8_validate() returns %FALSE if @max_len is
* positive and any of the @max_len bytes are NUL. * positive and any of the @max_len bytes are nul.
* *
* Returns %TRUE if all of @str was valid. Many GLib and GTK+ * Returns %TRUE if all of @str was valid. Many GLib and GTK+
* routines <emphasis>require</emphasis> valid UTF-8 as input; * routines require valid UTF-8 as input; so data read from a file
* so data read from a file or the network should be checked * or the network should be checked with g_utf8_validate() before
* with g_utf8_validate() before doing anything else with it. * doing anything else with it.
* *
* Return value: %TRUE if the text was valid UTF-8 * Return value: %TRUE if the text was valid UTF-8
*/ */

16
glib/gutils.c
View File

@ -1000,11 +1000,12 @@ static gchar *g_prgname = NULL;
/** /**
* g_get_prgname: * g_get_prgname:
* *
* Gets the name of the program. This name should <emphasis>not</emphasis> * Gets the name of the program. This name should not be localized,
* be localized, contrast with g_get_application_name(). * in contrast to g_get_application_name().
* (If you are using GDK or GTK+ the program name is set in gdk_init(), *
* If you are using GDK or GTK+ the program name is set in gdk_init(),
* which is called by gtk_init(). The program name is found by taking * which is called by gtk_init(). The program name is found by taking
* the last component of <literal>argv[0]</literal>.) * the last component of @argv[0].
* *
* Returns: the name of the program. The returned string belongs * Returns: the name of the program. The returned string belongs
* to GLib and must not be modified or freed. * to GLib and must not be modified or freed.
@ -1048,9 +1049,10 @@ g_get_prgname (void)
* g_set_prgname: * g_set_prgname:
* @prgname: the name of the program. * @prgname: the name of the program.
* *
* Sets the name of the program. This name should <emphasis>not</emphasis> * Sets the name of the program. This name should not be localized,
* be localized, contrast with g_set_application_name(). Note that for * in contrast to g_set_application_name().
* thread-safety reasons this function can only be called once. *
* Note that for thread-safety reasons this function can only be called once.
*/ */
void void
g_set_prgname (const gchar *prgname) g_set_prgname (const gchar *prgname)

24
gobject/gbinding.c
View File

@ -35,9 +35,9 @@
* G_BINDING_DEFAULT); * G_BINDING_DEFAULT);
* ]| * ]|
* *
* will cause <emphasis>object2:property-b</emphasis> to be updated every * will cause the property named "property-b" of @object2 to be updated
* time g_object_set() or the specific accessor changes the value of * every time g_object_set() or the specific accessor changes the value of
* <emphasis>object1:property-a</emphasis>. * the property "property-a" of @object1.
* *
* It is possible to create a bidirectional binding between two properties * It is possible to create a bidirectional binding between two properties
* of two #GObject instances, so that if either property changes, the * of two #GObject instances, so that if either property changes, the
@ -65,15 +65,15 @@
* NULL, NULL); * NULL, NULL);
* ]| * ]|
* *
* will keep the <emphasis>value</emphasis> property of the two adjustments * will keep the "value" property of the two adjustments in sync; the
* in sync; the <function>celsius_to_fahrenheit</function> function will be * @celsius_to_fahrenheit function will be called whenever the "value"
* called whenever the <emphasis>adjustment1:value</emphasis> property changes * property of @adjustment1 changes and will transform the current value
* and will transform the current value of the property before applying it * of the property before applying it to the "value" property of @adjustment2.
* to the <emphasis>adjustment2:value</emphasis> property; vice versa, the *
* <function>fahrenheit_to_celsius</function> function will be called whenever * Vice versa, the @fahrenheit_to_celsius function will be called whenever
* the <emphasis>adjustment2:value</emphasis> property changes, and will * the "value" property of @adjustment2 changes, and will transform the
* transform the current value of the property before applying it to the * current value of the property before applying it to the "value" property
* <emphasis>adjustment1:value</emphasis>. * of @adjustment1.
* *
* Note that #GBinding does not resolve cycles by itself; a cycle like * Note that #GBinding does not resolve cycles by itself; a cycle like
* *

43
gobject/gsignal.c
View File

@ -43,24 +43,26 @@
* and a general purpose notification mechanism * and a general purpose notification mechanism
* @title: Signals * @title: Signals
* *
* The basic concept of the signal system is that of the * The basic concept of the signal system is that of the emission
* <emphasis>emission</emphasis> of a signal. Signals are introduced * of a signal. Signals are introduced per-type and are identified
* per-type and are identified through strings. Signals introduced * through strings. Signals introduced for a parent type are available
* for a parent type are available in derived types as well, so * in derived types as well, so basically they are a per-type facility
* basically they are a per-type facility that is inherited. A signal * that is inherited.
* emission mainly involves invocation of a certain set of callbacks *
* in precisely defined manner. There are two main categories of such * A signal emission mainly involves invocation of a certain set of
* callbacks, per-object ones and user provided ones. * callbacks in precisely defined manner. There are two main categories
* of such callbacks, per-object ones and user provided ones.
* (Although signals can deal with any kind of instantiatable type, I'm * (Although signals can deal with any kind of instantiatable type, I'm
* referring to those types as "object types" in the following, simply * referring to those types as "object types" in the following, simply
* because that is the context most users will encounter signals in.) * because that is the context most users will encounter signals in.)
* The per-object callbacks are most often referred to as "object method * The per-object callbacks are most often referred to as "object method
* handler" or "default (signal) handler", while user provided callbacks are * handler" or "default (signal) handler", while user provided callbacks are
* usually just called "signal handler". * usually just called "signal handler".
*
* The object method handler is provided at signal creation time (this most * The object method handler is provided at signal creation time (this most
* frequently happens at the end of an object class' creation), while user * frequently happens at the end of an object class' creation), while user
* provided handlers are frequently connected and disconnected to/from a certain * provided handlers are frequently connected and disconnected to/from a
* signal on certain object instances. * certain signal on certain object instances.
* *
* A signal emission consists of five stages, unless prematurely stopped: * A signal emission consists of five stages, unless prematurely stopped:
* <variablelist> * <variablelist>
@ -68,13 +70,13 @@
* 1 - Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals * 1 - Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals
* </para></listitem></varlistentry> * </para></listitem></varlistentry>
* <varlistentry><term></term><listitem><para> * <varlistentry><term></term><listitem><para>
* 2 - Invocation of normal user-provided signal handlers (<emphasis>after</emphasis> flag %FALSE) * 2 - Invocation of normal user-provided signal handlers (where the @after flag is not set)
* </para></listitem></varlistentry> * </para></listitem></varlistentry>
* <varlistentry><term></term><listitem><para> * <varlistentry><term></term><listitem><para>
* 3 - Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals * 3 - Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals
* </para></listitem></varlistentry> * </para></listitem></varlistentry>
* <varlistentry><term></term><listitem><para> * <varlistentry><term></term><listitem><para>
* 4 - Invocation of user provided signal handlers, connected with an <emphasis>after</emphasis> flag of %TRUE * 4 - Invocation of user provided signal handlers (where the @after flag is set)
* </para></listitem></varlistentry> * </para></listitem></varlistentry>
* <varlistentry><term></term><listitem><para> * <varlistentry><term></term><listitem><para>
* 5 - Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals * 5 - Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals
@ -82,17 +84,20 @@
* </variablelist> * </variablelist>
* The user-provided signal handlers are called in the order they were * The user-provided signal handlers are called in the order they were
* connected in. * connected in.
*
* All handlers may prematurely stop a signal emission, and any number of * All handlers may prematurely stop a signal emission, and any number of
* handlers may be connected, disconnected, blocked or unblocked during * handlers may be connected, disconnected, blocked or unblocked during
* a signal emission. * a signal emission.
*
* There are certain criteria for skipping user handlers in stages 2 and 4 * There are certain criteria for skipping user handlers in stages 2 and 4
* of a signal emission. * of a signal emission.
* First, user handlers may be <emphasis>blocked</emphasis>, blocked handlers are omitted *
* during callback invocation, to return from the "blocked" state, a * First, user handlers may be blocked. Blocked handlers are omitted during
* handler has to get unblocked exactly the same amount of times * callback invocation, to return from the blocked state, a handler has to
* it has been blocked before. * get unblocked exactly the same amount of times it has been blocked before.
*
* Second, upon emission of a %G_SIGNAL_DETAILED signal, an additional * Second, upon emission of a %G_SIGNAL_DETAILED signal, an additional
* "detail" argument passed in to g_signal_emit() has to match the detail * @detail argument passed in to g_signal_emit() has to match the detail
* argument of the signal handler currently subject to invocation. * argument of the signal handler currently subject to invocation.
* Specification of no detail argument for signal handlers (omission of the * Specification of no detail argument for signal handlers (omission of the
* detail part of the signal specification upon connection) serves as a * detail part of the signal specification upon connection) serves as a
@ -3754,8 +3759,8 @@ type_debug_name (GType type)
* that a return of %TRUE stops the signal emission: no further * that a return of %TRUE stops the signal emission: no further
* callbacks will be invoked, while a return of %FALSE allows * callbacks will be invoked, while a return of %FALSE allows
* the emission to continue. The idea here is that a %TRUE return * the emission to continue. The idea here is that a %TRUE return
* indicates that the callback <emphasis>handled</emphasis> the signal, * indicates that the callback handled the signal, and no further
* and no further handling is needed. * handling is needed.
* *
* Since: 2.4 * Since: 2.4
* *

327
gobject/gtype.c
View File

@ -50,15 +50,18 @@
* unloaded at run-time as dynamic types may be. Static types are created * unloaded at run-time as dynamic types may be. Static types are created
* with g_type_register_static() that gets type specific information passed * with g_type_register_static() that gets type specific information passed
* in via a #GTypeInfo structure. * in via a #GTypeInfo structure.
*
* Dynamic types are created with g_type_register_dynamic() which takes a * Dynamic types are created with g_type_register_dynamic() which takes a
* #GTypePlugin structure instead. The remaining type information (the * #GTypePlugin structure instead. The remaining type information (the
* #GTypeInfo structure) is retrieved during runtime through #GTypePlugin * #GTypeInfo structure) is retrieved during runtime through #GTypePlugin
* and the g_type_plugin_*() API. * and the g_type_plugin_*() API.
*
* These registration functions are usually called only once from a * These registration functions are usually called only once from a
* function whose only purpose is to return the type identifier for a * function whose only purpose is to return the type identifier for a
* specific class. Once the type (or class or interface) is registered, * specific class. Once the type (or class or interface) is registered,
* it may be instantiated, inherited, or implemented depending on exactly * it may be instantiated, inherited, or implemented depending on exactly
* what sort of type it is. * what sort of type it is.
*
* There is also a third registration function for registering fundamental * There is also a third registration function for registering fundamental
* types called g_type_register_fundamental() which requires both a #GTypeInfo * types called g_type_register_fundamental() which requires both a #GTypeInfo
* structure and a #GTypeFundamentalInfo structure but it is seldom used * structure and a #GTypeFundamentalInfo structure but it is seldom used
@ -71,11 +74,10 @@
* separately (typically by using #GArray or #GPtrArray) and put a pointer * separately (typically by using #GArray or #GPtrArray) and put a pointer
* to the buffer in the structure. * to the buffer in the structure.
* *
* A final word about type names. * A final word about type names: Such an identifier needs to be at least
* Such an identifier needs to be at least three characters long. There is no * three characters long. There is no upper length limit. The first character
* upper length limit. The first character needs to be a letter (a-z or A-Z) * needs to be a letter (a-z or A-Z) or an underscore '_'. Subsequent
* or an underscore '_'. Subsequent characters can be letters, numbers or * characters can be letters, numbers or any of '-_+'.
* any of '-_+'.
*/ */
@ -396,15 +398,15 @@ lookup_type_node_I (register GType utype)
/** /**
* g_type_get_type_registration_serial: * g_type_get_type_registration_serial:
* *
* Returns an opaque serial number that represents the state of the set of * Returns an opaque serial number that represents the state of the set
* registered types. Any time a type is registered this serial changes, * of registered types. Any time a type is registered this serial changes,
* which means you can cache information based on type lookups (such as * which means you can cache information based on type lookups (such as
* g_type_from_name()) and know if the cache is still valid at a later * g_type_from_name()) and know if the cache is still valid at a later
* time by comparing the current serial with the one at the type lookup. * time by comparing the current serial with the one at the type lookup.
* *
* Since: 2.36 * Since: 2.36
* *
* Returns: An unsigned int, representing the state of type registrations. * Returns: An unsigned int, representing the state of type registrations
*/ */
guint guint
g_type_get_type_registration_serial (void) g_type_get_type_registration_serial (void)
@ -1548,8 +1550,8 @@ type_iface_add_prerequisite_W (TypeNode *iface,
/** /**
* g_type_interface_add_prerequisite: * g_type_interface_add_prerequisite:
* @interface_type: #GType value of an interface type. * @interface_type: #GType value of an interface type
* @prerequisite_type: #GType value of an interface or instantiatable type. * @prerequisite_type: #GType value of an interface or instantiatable type
* *
* Adds @prerequisite_type to the list of prerequisites of @interface_type. * Adds @prerequisite_type to the list of prerequisites of @interface_type.
* This means that any type implementing @interface_type must also implement * This means that any type implementing @interface_type must also implement
@ -1766,7 +1768,7 @@ type_iface_blow_holder_info_Wm (TypeNode *iface,
/** /**
* g_type_create_instance: (skip) * g_type_create_instance: (skip)
* @type: An instantiatable type to create an instance for. * @type: an instantiatable type to create an instance for
* *
* Creates and initializes an instance of @type if @type is valid and * Creates and initializes an instance of @type if @type is valid and
* can be instantiated. The type system only performs basic allocation * can be instantiated. The type system only performs basic allocation
@ -1774,16 +1776,16 @@ type_iface_blow_holder_info_Wm (TypeNode *iface,
* happen through functions supplied by the type's fundamental type * happen through functions supplied by the type's fundamental type
* implementation. So use of g_type_create_instance() is reserved for * implementation. So use of g_type_create_instance() is reserved for
* implementators of fundamental types only. E.g. instances of the * implementators of fundamental types only. E.g. instances of the
* #GObject hierarchy should be created via g_object_new() and * #GObject hierarchy should be created via g_object_new() and never
* <emphasis>never</emphasis> directly through * directly through g_type_create_instance() which doesn't handle things
* g_type_create_instance() which doesn't handle things like singleton * like singleton objects or object construction.
* objects or object construction. Note: Do <emphasis>not</emphasis>
* use this function, unless you're implementing a fundamental
* type. Also language bindings should <emphasis>not</emphasis> use
* this function but g_object_new() instead.
* *
* Returns: An allocated and initialized instance, subject to further * Note: Do not use this function, unless you're implementing a
* treatment by the fundamental type implementation. * fundamental type. Also language bindings should not use this
* function, but g_object_new() instead.
*
* Returns: an allocated and initialized instance, subject to further
* treatment by the fundamental type implementation
*/ */
GTypeInstance* GTypeInstance*
g_type_create_instance (GType type) g_type_create_instance (GType type)
@ -1872,7 +1874,7 @@ g_type_create_instance (GType type)
/** /**
* g_type_free_instance: * g_type_free_instance:
* @instance: an instance of a type. * @instance: an instance of a type
* *
* Frees an instance of a type, returning it to the instance pool for * Frees an instance of a type, returning it to the instance pool for
* the type, if there is one. * the type, if there is one.
@ -2512,14 +2514,14 @@ g_type_remove_class_cache_func (gpointer cache_data,
* g_type_add_interface_check: (skip) * g_type_add_interface_check: (skip)
* @check_data: data to pass to @check_func * @check_data: data to pass to @check_func
* @check_func: function to be called after each interface * @check_func: function to be called after each interface
* is initialized. * is initialized
* *
* Adds a function to be called after an interface vtable is * Adds a function to be called after an interface vtable is
* initialized for any class (i.e. after the @interface_init member of * initialized for any class (i.e. after the @interface_init
* #GInterfaceInfo has been called). * member of #GInterfaceInfo has been called).
* *
* This function is useful when you want to check an invariant that * This function is useful when you want to check an invariant
* depends on the interfaces of a class. For instance, the * that depends on the interfaces of a class. For instance, the
* implementation of #GObject uses this facility to check that an * implementation of #GObject uses this facility to check that an
* object implements all of the properties that are defined on its * object implements all of the properties that are defined on its
* interfaces. * interfaces.
@ -2584,21 +2586,21 @@ g_type_remove_interface_check (gpointer check_data,
/* --- type registration --- */ /* --- type registration --- */
/** /**
* g_type_register_fundamental: * g_type_register_fundamental:
* @type_id: A predefined type identifier. * @type_id: a predefined type identifier
* @type_name: 0-terminated string used as the name of the new type. * @type_name: 0-terminated string used as the name of the new type
* @info: The #GTypeInfo structure for this type. * @info: #GTypeInfo structure for this type
* @finfo: The #GTypeFundamentalInfo structure for this type. * @finfo: #GTypeFundamentalInfo structure for this type
* @flags: Bitwise combination of #GTypeFlags values. * @flags: bitwise combination of #GTypeFlags values
* *
* Registers @type_id as the predefined identifier and @type_name as the * Registers @type_id as the predefined identifier and @type_name as the
* name of a fundamental type. If @type_id is already registered, or a type * name of a fundamental type. If @type_id is already registered, or a
* named @type_name is already registered, the behaviour is undefined. The type * type named @type_name is already registered, the behaviour is undefined.
* system uses the information contained in the #GTypeInfo structure pointed to * The type system uses the information contained in the #GTypeInfo structure
* by @info and the #GTypeFundamentalInfo structure pointed to by @finfo to * pointed to by @info and the #GTypeFundamentalInfo structure pointed to by
* manage the type and its instances. The value of @flags determines additional * @finfo to manage the type and its instances. The value of @flags determines
* characteristics of the fundamental type. * additional characteristics of the fundamental type.
* *
* Returns: The predefined type identifier. * Returns: the predefined type identifier
*/ */
GType GType
g_type_register_fundamental (GType type_id, g_type_register_fundamental (GType type_id,
@ -2654,13 +2656,13 @@ g_type_register_fundamental (GType type_id,
/** /**
* g_type_register_static_simple: (skip) * g_type_register_static_simple: (skip)
* @parent_type: Type from which this type will be derived. * @parent_type: type from which this type will be derived
* @type_name: 0-terminated string used as the name of the new type. * @type_name: 0-terminated string used as the name of the new type
* @class_size: Size of the class structure (see #GTypeInfo) * @class_size: size of the class structure (see #GTypeInfo)
* @class_init: Location of the class initialization function (see #GTypeInfo) * @class_init: location of the class initialization function (see #GTypeInfo)
* @instance_size: Size of the instance structure (see #GTypeInfo) * @instance_size: size of the instance structure (see #GTypeInfo)
* @instance_init: Location of the instance initialization function (see #GTypeInfo) * @instance_init: location of the instance initialization function (see #GTypeInfo)
* @flags: Bitwise combination of #GTypeFlags values. * @flags: bitwise combination of #GTypeFlags values
* *
* Registers @type_name as the name of a new static type derived from * Registers @type_name as the name of a new static type derived from
* @parent_type. The value of @flags determines the nature (e.g. * @parent_type. The value of @flags determines the nature (e.g.
@ -2669,7 +2671,7 @@ g_type_register_fundamental (GType type_id,
* *
* Since: 2.12 * Since: 2.12
* *
* Returns: The new type identifier. * Returns: the new type identifier
*/ */
GType GType
g_type_register_static_simple (GType parent_type, g_type_register_static_simple (GType parent_type,
@ -2704,10 +2706,10 @@ g_type_register_static_simple (GType parent_type,
/** /**
* g_type_register_static: * g_type_register_static:
* @parent_type: Type from which this type will be derived. * @parent_type: type from which this type will be derived
* @type_name: 0-terminated string used as the name of the new type. * @type_name: 0-terminated string used as the name of the new type
* @info: The #GTypeInfo structure for this type. * @info: #GTypeInfo structure for this type
* @flags: Bitwise combination of #GTypeFlags values. * @flags: bitwise combination of #GTypeFlags values
* *
* Registers @type_name as the name of a new static type derived from * Registers @type_name as the name of a new static type derived from
* @parent_type. The type system uses the information contained in the * @parent_type. The type system uses the information contained in the
@ -2715,7 +2717,7 @@ g_type_register_static_simple (GType parent_type,
* instances (if not abstract). The value of @flags determines the nature * instances (if not abstract). The value of @flags determines the nature
* (e.g. abstract or not) of the type. * (e.g. abstract or not) of the type.
* *
* Returns: The new type identifier. * Returns: the new type identifier
*/ */
GType GType
g_type_register_static (GType parent_type, g_type_register_static (GType parent_type,
@ -2759,10 +2761,10 @@ g_type_register_static (GType parent_type,
/** /**
* g_type_register_dynamic: * g_type_register_dynamic:
* @parent_type: Type from which this type will be derived. * @parent_type: type from which this type will be derived
* @type_name: 0-terminated string used as the name of the new type. * @type_name: 0-terminated string used as the name of the new type
* @plugin: The #GTypePlugin structure to retrieve the #GTypeInfo from. * @plugin: #GTypePlugin structure to retrieve the #GTypeInfo from
* @flags: Bitwise combination of #GTypeFlags values. * @flags: bitwise combination of #GTypeFlags values
* *
* Registers @type_name as the name of a new dynamic type derived from * Registers @type_name as the name of a new dynamic type derived from
* @parent_type. The type system uses the information contained in the * @parent_type. The type system uses the information contained in the
@ -2770,7 +2772,7 @@ g_type_register_static (GType parent_type,
* instances (if not abstract). The value of @flags determines the nature * instances (if not abstract). The value of @flags determines the nature
* (e.g. abstract or not) of the type. * (e.g. abstract or not) of the type.
* *
* Returns: The new type identifier or #G_TYPE_INVALID if registration failed. * Returns: the new type identifier or #G_TYPE_INVALID if registration failed
*/ */
GType GType
g_type_register_dynamic (GType parent_type, g_type_register_dynamic (GType parent_type,
@ -2803,14 +2805,14 @@ g_type_register_dynamic (GType parent_type,
/** /**
* g_type_add_interface_static: * g_type_add_interface_static:
* @instance_type: #GType value of an instantiable type. * @instance_type: #GType value of an instantiable type
* @interface_type: #GType value of an interface type. * @interface_type: #GType value of an interface type
* @info: The #GInterfaceInfo structure for this * @info: #GInterfaceInfo structure for this
* (@instance_type, @interface_type) combination. * (@instance_type, @interface_type) combination
* *
* Adds the static @interface_type to @instantiable_type. The * Adds the static @interface_type to @instantiable_type.
* information contained in the #GInterfaceInfo structure pointed to by * The information contained in the #GInterfaceInfo structure
* @info is used to manage the relationship. * pointed to by @info is used to manage the relationship.
*/ */
void void
g_type_add_interface_static (GType instance_type, g_type_add_interface_static (GType instance_type,
@ -2840,9 +2842,9 @@ g_type_add_interface_static (GType instance_type,
/** /**
* g_type_add_interface_dynamic: * g_type_add_interface_dynamic:
* @instance_type: the #GType value of an instantiable type. * @instance_type: #GType value of an instantiable type
* @interface_type: the #GType value of an interface type. * @interface_type: #GType value of an interface type
* @plugin: the #GTypePlugin structure to retrieve the #GInterfaceInfo from. * @plugin: #GTypePlugin structure to retrieve the #GInterfaceInfo from
* *
* Adds the dynamic @interface_type to @instantiable_type. The information * Adds the dynamic @interface_type to @instantiable_type. The information
* contained in the #GTypePlugin structure pointed to by @plugin * contained in the #GTypePlugin structure pointed to by @plugin
@ -2878,14 +2880,14 @@ g_type_add_interface_dynamic (GType instance_type,
/* --- public API functions --- */ /* --- public API functions --- */
/** /**
* g_type_class_ref: * g_type_class_ref:
* @type: Type ID of a classed type. * @type: type ID of a classed type
* *
* Increments the reference count of the class structure belonging to * Increments the reference count of the class structure belonging to
* @type. This function will demand-create the class if it doesn't * @type. This function will demand-create the class if it doesn't
* exist already. * exist already.
* *
* Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass * Returns: (type GObject.TypeClass) (transfer none): the #GTypeClass
* structure for the given type ID. * structure for the given type ID
*/ */
gpointer gpointer
g_type_class_ref (GType type) g_type_class_ref (GType type)
@ -2944,8 +2946,7 @@ g_type_class_ref (GType type)
/** /**
* g_type_class_unref: * g_type_class_unref:
* @g_class: (type GObject.TypeClass): The #GTypeClass structure to * @g_class: (type GObject.TypeClass): a #GTypeClass structure to unref
* unreference.
* *
* Decrements the reference count of the class structure being passed in. * Decrements the reference count of the class structure being passed in.
* Once the last reference count of a class has been released, classes * Once the last reference count of a class has been released, classes
@ -2970,12 +2971,11 @@ g_type_class_unref (gpointer g_class)
/** /**
* g_type_class_unref_uncached: (skip) * g_type_class_unref_uncached: (skip)
* @g_class: (type GObject.TypeClass): The #GTypeClass structure to * @g_class: (type GObject.TypeClass): a #GTypeClass structure to unref
* unreference.
* *
* A variant of g_type_class_unref() for use in #GTypeClassCacheFunc * A variant of g_type_class_unref() for use in #GTypeClassCacheFunc
* implementations. It unreferences a class without consulting the chain * implementations. It unreferences a class without consulting the chain
* of #GTypeClassCacheFunc<!-- -->s, avoiding the recursion which would occur * of #GTypeClassCacheFuncs, avoiding the recursion which would occur
* otherwise. * otherwise.
*/ */
void void
@ -2996,16 +2996,17 @@ g_type_class_unref_uncached (gpointer g_class)
/** /**
* g_type_class_peek: * g_type_class_peek:
* @type: Type ID of a classed type. * @type: type ID of a classed type
* *
* This function is essentially the same as g_type_class_ref(), except that * This function is essentially the same as g_type_class_ref(),
* the classes reference count isn't incremented. As a consequence, this function * except that the classes reference count isn't incremented.
* may return %NULL if the class of the type passed in does not currently * As a consequence, this function may return %NULL if the class
* exist (hasn't been referenced before). * of the type passed in does not currently exist (hasn't been
* referenced before).
* *
* Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass * Returns: (type GObject.TypeClass) (transfer none): the #GTypeClass
* structure for the given type ID or %NULL if the class does not * structure for the given type ID or %NULL if the class does not
* currently exist. * currently exist
*/ */
gpointer gpointer
g_type_class_peek (GType type) g_type_class_peek (GType type)
@ -3026,15 +3027,16 @@ g_type_class_peek (GType type)
/** /**
* g_type_class_peek_static: * g_type_class_peek_static:
* @type: Type ID of a classed type. * @type: type ID of a classed type
* *
* A more efficient version of g_type_class_peek() which works only for * A more efficient version of g_type_class_peek() which works only for
* static types. * static types.
* *
* Since: 2.4 * Returns: (type GObject.TypeClass) (transfer none): the #GTypeClass
* Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass
* structure for the given type ID or %NULL if the class does not * structure for the given type ID or %NULL if the class does not
* currently exist or is dynamically loaded. * currently exist or is dynamically loaded
*
* Since: 2.4
*/ */
gpointer gpointer
g_type_class_peek_static (GType type) g_type_class_peek_static (GType type)
@ -3056,8 +3058,8 @@ g_type_class_peek_static (GType type)
/** /**
* g_type_class_peek_parent: * g_type_class_peek_parent:
* @g_class: (type GObject.TypeClass): The #GTypeClass structure to * @g_class: (type GObject.TypeClass): the #GTypeClass structure to
* retrieve the parent class for. * retrieve the parent class for
* *
* This is a convenience function often needed in class initializers. * This is a convenience function often needed in class initializers.
* It returns the class structure of the immediate parent type of the * It returns the class structure of the immediate parent type of the
@ -3070,8 +3072,8 @@ g_type_class_peek_static (GType type)
* g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class))); * g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class)));
* </programlisting> * </programlisting>
* *
* Returns: (type GObject.TypeClass) (transfer none): The parent class * Returns: (type GObject.TypeClass) (transfer none): the parent class
* of @g_class. * of @g_class
*/ */
gpointer gpointer
g_type_class_peek_parent (gpointer g_class) g_type_class_peek_parent (gpointer g_class)
@ -3099,14 +3101,14 @@ g_type_class_peek_parent (gpointer g_class)
/** /**
* g_type_interface_peek: * g_type_interface_peek:
* @instance_class: (type GObject.TypeClass): A #GTypeClass structure. * @instance_class: (type GObject.TypeClass): a #GTypeClass structure
* @iface_type: An interface ID which this class conforms to. * @iface_type: an interface ID which this class conforms to
* *
* Returns the #GTypeInterface structure of an interface to which the * Returns the #GTypeInterface structure of an interface to which the
* passed in class conforms. * passed in class conforms.
* *
* Returns: (type GObject.TypeInterface) (transfer none): The GTypeInterface * Returns: (type GObject.TypeInterface) (transfer none): the #GTypeInterface
* structure of iface_type if implemented by @instance_class, %NULL * structure of @iface_type if implemented by @instance_class, %NULL
* otherwise * otherwise
*/ */
gpointer gpointer
@ -3132,17 +3134,17 @@ g_type_interface_peek (gpointer instance_class,
/** /**
* g_type_interface_peek_parent: * g_type_interface_peek_parent:
* @g_iface: (type GObject.TypeInterface): A #GTypeInterface structure. * @g_iface: (type GObject.TypeInterface): a #GTypeInterface structure
* *
* Returns the corresponding #GTypeInterface structure of the parent type * Returns the corresponding #GTypeInterface structure of the parent type
* of the instance type to which @g_iface belongs. This is useful when * of the instance type to which @g_iface belongs. This is useful when
* deriving the implementation of an interface from the parent type and * deriving the implementation of an interface from the parent type and
* then possibly overriding some methods. * then possibly overriding some methods.
* *
* Returns: (transfer none) (type GObject.TypeInterface): The * Returns: (transfer none) (type GObject.TypeInterface): the
* corresponding #GTypeInterface structure of the parent type of the * corresponding #GTypeInterface structure of the parent type of the
* instance type to which @g_iface belongs, or %NULL if the parent * instance type to which @g_iface belongs, or %NULL if the parent
* type doesn't conform to the interface. * type doesn't conform to the interface
*/ */
gpointer gpointer
g_type_interface_peek_parent (gpointer g_iface) g_type_interface_peek_parent (gpointer g_iface)
@ -3234,8 +3236,8 @@ g_type_default_interface_ref (GType g_type)
* Since: 2.4 * Since: 2.4
* *
* Returns: (type GObject.TypeInterface) (transfer none): the default * Returns: (type GObject.TypeInterface) (transfer none): the default
* vtable for the interface, or %NULL if the type is not currently in * vtable for the interface, or %NULL if the type is not currently
* use. * in use
*/ */
gpointer gpointer
g_type_default_interface_peek (GType g_type) g_type_default_interface_peek (GType g_type)
@ -3255,8 +3257,7 @@ g_type_default_interface_peek (GType g_type)
/** /**
* g_type_default_interface_unref: * g_type_default_interface_unref:
* @g_iface: (type GObject.TypeInterface): the default vtable * @g_iface: (type GObject.TypeInterface): the default vtable
* structure for a interface, as returned by * structure for a interface, as returned by g_type_default_interface_ref()
* g_type_default_interface_ref()
* *
* Decrements the reference count for the type corresponding to the * Decrements the reference count for the type corresponding to the
* interface default vtable @g_iface. If the type is dynamic, then * interface default vtable @g_iface. If the type is dynamic, then
@ -3284,7 +3285,7 @@ g_type_default_interface_unref (gpointer g_iface)
/** /**
* g_type_name: * g_type_name:
* @type: Type to return name for. * @type: type to return name for
* *
* Get the unique name that is assigned to a type ID. Note that this * Get the unique name that is assigned to a type ID. Note that this
* function (like all other GType API) cannot cope with invalid type * function (like all other GType API) cannot cope with invalid type
@ -3292,7 +3293,7 @@ g_type_default_interface_unref (gpointer g_iface)
* other validly registered type ID, but randomized type IDs should * other validly registered type ID, but randomized type IDs should
* not be passed in and will most likely lead to a crash. * not be passed in and will most likely lead to a crash.
* *
* Returns: Static type name or %NULL. * Returns: static type name or %NULL
*/ */
const gchar * const gchar *
g_type_name (GType type) g_type_name (GType type)
@ -3308,11 +3309,11 @@ g_type_name (GType type)
/** /**
* g_type_qname: * g_type_qname:
* @type: Type to return quark of type name for. * @type: type to return quark of type name for
* *
* Get the corresponding quark of the type IDs name. * Get the corresponding quark of the type IDs name.
* *
* Returns: The type names quark or 0. * Returns: the type names quark or 0
*/ */
GQuark GQuark
g_type_qname (GType type) g_type_qname (GType type)
@ -3326,14 +3327,14 @@ g_type_qname (GType type)
/** /**
* g_type_from_name: * g_type_from_name:
* @name: Type name to lookup. * @name: type name to lookup
* *
* Lookup the type ID from a given type name, returning 0 if no type * Lookup the type ID from a given type name, returning 0 if no type
* has been registered under this name (this is the preferred method * has been registered under this name (this is the preferred method
* to find out by name whether a specific type has been registered * to find out by name whether a specific type has been registered
* yet). * yet).
* *
* Returns: Corresponding type ID or 0. * Returns: corresponding type ID or 0
*/ */
GType GType
g_type_from_name (const gchar *name) g_type_from_name (const gchar *name)
@ -3351,12 +3352,12 @@ g_type_from_name (const gchar *name)
/** /**
* g_type_parent: * g_type_parent:
* @type: The derived type. * @type: the derived type
* *
* Return the direct parent type of the passed in type. If the passed * Return the direct parent type of the passed in type. If the passed
* in type has no parent, i.e. is a fundamental type, 0 is returned. * in type has no parent, i.e. is a fundamental type, 0 is returned.
* *
* Returns: The parent type. * Returns: the parent type
*/ */
GType GType
g_type_parent (GType type) g_type_parent (GType type)
@ -3370,12 +3371,12 @@ g_type_parent (GType type)
/** /**
* g_type_depth: * g_type_depth:
* @type: A #GType value. * @type: a #GType
* *
* Returns the length of the ancestry of the passed in type. This * Returns the length of the ancestry of the passed in type. This
* includes the type itself, so that e.g. a fundamental type has depth 1. * includes the type itself, so that e.g. a fundamental type has depth 1.
* *
* Returns: The depth of @type. * Returns: the depth of @type
*/ */
guint guint
g_type_depth (GType type) g_type_depth (GType type)
@ -3389,8 +3390,8 @@ g_type_depth (GType type)
/** /**
* g_type_next_base: * g_type_next_base:
* @leaf_type: Descendant of @root_type and the type to be returned. * @leaf_type: descendant of @root_type and the type to be returned
* @root_type: Immediate parent of the returned type. * @root_type: immediate parent of the returned type
* *
* Given a @leaf_type and a @root_type which is contained in its * Given a @leaf_type and a @root_type which is contained in its
* anchestry, return the type that @root_type is the immediate parent * anchestry, return the type that @root_type is the immediate parent
@ -3400,7 +3401,7 @@ g_type_depth (GType type)
* be used to determine the types and order in which the leaf type is * be used to determine the types and order in which the leaf type is
* descended from the root type. * descended from the root type.
* *
* Returns: Immediate child of @root_type and anchestor of @leaf_type. * Returns: immediate child of @root_type and anchestor of @leaf_type
*/ */
GType GType
g_type_next_base (GType type, g_type_next_base (GType type,
@ -3487,14 +3488,15 @@ type_node_conforms_to_U (TypeNode *node,
/** /**
* g_type_is_a: * g_type_is_a:
* @type: Type to check anchestry for. * @type: type to check anchestry for
* @is_a_type: Possible anchestor of @type or interface @type could conform to. * @is_a_type: possible anchestor of @type or interface that @type
* could conform to
* *
* If @is_a_type is a derivable type, check whether @type is a * If @is_a_type is a derivable type, check whether @type is a
* descendant of @is_a_type. If @is_a_type is an interface, check * descendant of @is_a_type. If @is_a_type is an interface, check
* whether @type conforms to it. * whether @type conforms to it.
* *
* Returns: %TRUE if @type is_a @is_a_type holds true. * Returns: %TRUE if @type is a @is_a_type
*/ */
gboolean gboolean
g_type_is_a (GType type, g_type_is_a (GType type,
@ -3512,15 +3514,15 @@ g_type_is_a (GType type,
/** /**
* g_type_children: * g_type_children:
* @type: The parent type. * @type: the parent type
* @n_children: (out) (allow-none): Optional #guint pointer to contain * @n_children: (out) (allow-none): location to store the length of
* the number of child types. * the returned array, or %NULL
* *
* Return a newly allocated and 0-terminated array of type IDs, listing the * Return a newly allocated and 0-terminated array of type IDs, listing
* child types of @type. The return value has to be g_free()ed after use. * the child types of @type.
* *
* Returns: (array length=n_children) (transfer full): Newly allocated * Returns: (array length=n_children) (transfer full): Newly allocated
* and 0-terminated array of child types. * and 0-terminated array of child types, free with g_free()
*/ */
GType* GType*
g_type_children (GType type, g_type_children (GType type,
@ -3555,16 +3557,15 @@ g_type_children (GType type,
/** /**
* g_type_interfaces: * g_type_interfaces:
* @type: The type to list interface types for. * @type: the type to list interface types for
* @n_interfaces: (out) (allow-none): Optional #guint pointer to * @n_interfaces: (out) (allow-none): location to store the length of
* contain the number of interface types. * the returned array, or %NULL
* *
* Return a newly allocated and 0-terminated array of type IDs, listing the * Return a newly allocated and 0-terminated array of type IDs, listing
* interface types that @type conforms to. The return value has to be * the interface types that @type conforms to.
* g_free()ed after use.
* *
* Returns: (array length=n_interfaces) (transfer full): Newly * Returns: (array length=n_interfaces) (transfer full): Newly allocated
* allocated and 0-terminated array of interface types. * and 0-terminated array of interface types, free with g_free()
*/ */
GType* GType*
g_type_interfaces (GType type, g_type_interfaces (GType type,
@ -3771,9 +3772,9 @@ type_add_flags_W (TypeNode *node,
/** /**
* g_type_query: * g_type_query:
* @type: the #GType value of a static, classed type. * @type: #GType of a static, classed type
* @query: (out caller-allocates): A user provided structure that is * @query: (out caller-allocates): a user provided structure that is
* filled in with constant values upon success. * filled in with constant values upon success
* *
* Queries the type system for information about a specific type. * Queries the type system for information about a specific type.
* This function will fill in a user-provided structure to hold * This function will fill in a user-provided structure to hold
@ -3849,13 +3850,12 @@ g_type_test_flags (GType type,
/** /**
* g_type_get_plugin: * g_type_get_plugin:
* @type: The #GType to retrieve the plugin for. * @type: #GType to retrieve the plugin for
* *
* Returns the #GTypePlugin structure for @type or * Returns the #GTypePlugin structure for @type.
* %NULL if @type does not have a #GTypePlugin structure.
* *
* Returns: (transfer none): The corresponding plugin if @type is a * Returns: (transfer none): the corresponding plugin
* dynamic type, %NULL otherwise. * if @type is a dynamic type, %NULL otherwise
*/ */
GTypePlugin* GTypePlugin*
g_type_get_plugin (GType type) g_type_get_plugin (GType type)
@ -3869,16 +3869,16 @@ g_type_get_plugin (GType type)
/** /**
* g_type_interface_get_plugin: * g_type_interface_get_plugin:
* @instance_type: the #GType value of an instantiatable type. * @instance_type: #GType of an instantiatable type
* @interface_type: the #GType value of an interface type. * @interface_type: #GType of an interface type
* *
* Returns the #GTypePlugin structure for the dynamic interface * Returns the #GTypePlugin structure for the dynamic interface
* @interface_type which has been added to @instance_type, or %NULL if * @interface_type which has been added to @instance_type, or %NULL
* @interface_type has not been added to @instance_type or does not * if @interface_type has not been added to @instance_type or does
* have a #GTypePlugin structure. See g_type_add_interface_dynamic(). * not have a #GTypePlugin structure. See g_type_add_interface_dynamic().
* *
* Returns: (transfer none): the #GTypePlugin for the dynamic * Returns: (transfer none): the #GTypePlugin for the dynamic
* interface @interface_type of @instance_type. * interface @interface_type of @instance_type
*/ */
GTypePlugin* GTypePlugin*
g_type_interface_get_plugin (GType instance_type, g_type_interface_get_plugin (GType instance_type,
@ -3924,8 +3924,8 @@ g_type_interface_get_plugin (GType instance_type,
* The returned type ID represents the highest currently registered * The returned type ID represents the highest currently registered
* fundamental type identifier. * fundamental type identifier.
* *
* Returns: The nextmost fundamental type ID to be registered, * Returns: the next available fundamental type ID to be registered,
* or 0 if the type system ran out of fundamental type IDs. * or 0 if the type system ran out of fundamental type IDs
*/ */
GType GType
g_type_fundamental_next (void) g_type_fundamental_next (void)
@ -3944,7 +3944,7 @@ g_type_fundamental_next (void)
* @type_id: valid type ID * @type_id: valid type ID
* *
* Internal function, used to extract the fundamental type ID portion. * Internal function, used to extract the fundamental type ID portion.
* use G_TYPE_FUNDAMENTAL() instead. * Use G_TYPE_FUNDAMENTAL() instead.
* *
* Returns: fundamental type ID * Returns: fundamental type ID
*/ */
@ -4058,12 +4058,12 @@ g_type_check_class_cast (GTypeClass *type_class,
/** /**
* g_type_check_instance: * g_type_check_instance:
* @instance: A valid #GTypeInstance structure. * @instance: a valid #GTypeInstance structure
* *
* Private helper function to aid implementation of the G_TYPE_CHECK_INSTANCE() * Private helper function to aid implementation of the
* macro. * G_TYPE_CHECK_INSTANCE() macro.
* *
* Returns: %TRUE if @instance is valid, %FALSE otherwise. * Returns: %TRUE if @instance is valid, %FALSE otherwise
*/ */
gboolean gboolean
g_type_check_instance (GTypeInstance *type_instance) g_type_check_instance (GTypeInstance *type_instance)
@ -4154,15 +4154,16 @@ g_type_check_value_holds (GValue *value,
/** /**
* g_type_value_table_peek: (skip) * g_type_value_table_peek: (skip)
* @type: A #GType value. * @type: a #GType
* *
* Returns the location of the #GTypeValueTable associated with @type. * Returns the location of the #GTypeValueTable associated with @type.
* <emphasis>Note that this function should only be used from source code
* that implements or has internal knowledge of the implementation of
* @type.</emphasis>
* *
* Returns: Location of the #GTypeValueTable associated with @type or * Note that this function should only be used from source code
* %NULL if there is no #GTypeValueTable associated with @type. * that implements or has internal knowledge of the implementation of
* @type.
*
* Returns: location of the #GTypeValueTable associated with @type or
* %NULL if there is no #GTypeValueTable associated with @type
*/ */
GTypeValueTable* GTypeValueTable*
g_type_value_table_peek (GType type) g_type_value_table_peek (GType type)
@ -4266,8 +4267,8 @@ _g_type_boxed_init (GType type,
/* --- initialization --- */ /* --- initialization --- */
/** /**
* g_type_init_with_debug_flags: * g_type_init_with_debug_flags:
* @debug_flags: Bitwise combination of #GTypeDebugFlags values for * @debug_flags: bitwise combination of #GTypeDebugFlags values for
* debugging purposes. * debugging purposes
* *
* This function used to initialise the type system with debugging * This function used to initialise the type system with debugging
* flags. Since GLib 2.36, the type system is initialised automatically * flags. Since GLib 2.36, the type system is initialised automatically
@ -4403,7 +4404,7 @@ gobject_init_ctor (void)
/** /**
* g_type_class_add_private: * g_type_class_add_private:
* @g_class: class structure for an instantiatable type * @g_class: class structure for an instantiatable type
* @private_size: size of private structure. * @private_size: size of private structure
* *
* Registers a private structure for an instantiatable type. * Registers a private structure for an instantiatable type.
* *
@ -4681,8 +4682,8 @@ g_type_class_get_instance_private_offset (gpointer g_class)
/** /**
* g_type_add_class_private: * g_type_add_class_private:
* @class_type: GType of an classed type. * @class_type: GType of an classed type
* @private_size: size of private structure. * @private_size: size of private structure
* *
* Registers a private class structure for a classed type; * Registers a private class structure for a classed type;
* when the class is allocated, the private structures for * when the class is allocated, the private structures for
@ -4777,7 +4778,7 @@ g_type_class_get_private (GTypeClass *klass,
/** /**
* g_type_ensure: * g_type_ensure:
* @type: a #GType. * @type: a #GType
* *
* Ensures that the indicated @type has been registered with the * Ensures that the indicated @type has been registered with the
* type system, and its _class_init() method has been run. * type system, and its _class_init() method has been run.