From 4d12e0d66f1641a6eb2ba9c65579935136f6ef46 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Fri, 31 Jan 2014 20:34:33 -0500 Subject: [PATCH] Docs: Don't use the emphasis tag Most of the time, the text read just as well without the extra boldness. --- gio/gasyncresult.c | 11 +- gio/gcancellable.c | 16 +- gio/gdatainputstream.c | 14 +- gio/gdbusconnection.c | 7 +- gio/gdbusmethodinvocation.c | 2 +- gio/gdbusobjectmanagerclient.c | 13 +- gio/gdbusproxy.c | 2 +- gio/gdbusutils.c | 7 +- gio/gnetworking.c | 9 +- gio/gnetworkmonitor.c | 7 +- gio/goutputstream.c | 26 ++- gio/gresolver.c | 5 +- gio/gsettings.c | 3 +- gio/gtask.c | 4 +- glib/docs.c | 34 ++-- glib/gcharset.c | 2 +- glib/gconvert.c | 17 +- glib/gdate.c | 24 +-- glib/gerror.c | 96 +++++------ glib/ggettext.c | 4 +- glib/giochannel.c | 3 +- glib/gmain.c | 7 +- glib/gmem.c | 18 ++- glib/gmessages.c | 3 +- glib/goption.c | 6 +- glib/gpattern.c | 17 +- glib/gquark.c | 34 ++-- glib/gqueue.c | 18 +-- glib/gsequence.c | 153 +++++++++--------- glib/gstrfuncs.c | 30 ++-- glib/gthread.c | 7 +- glib/gutf8.c | 8 +- glib/gutils.c | 18 ++- gobject/gbinding.c | 24 +-- gobject/gsignal.c | 43 ++--- gobject/gtype.c | 359 +++++++++++++++++++++-------------------- 36 files changed, 515 insertions(+), 536 deletions(-) diff --git a/gio/gasyncresult.c b/gio/gasyncresult.c index 10a3b1e..6283663 100644 --- a/gio/gasyncresult.c +++ b/gio/gasyncresult.c @@ -105,12 +105,11 @@ * I/O * priority Many I/O-related asynchronous * operations have a priority parameter, which is used in certain - * cases to determine the order in which operations are executed. They - * are not used to determine system-wide I/O - * scheduling. Priorities are integers, with lower numbers indicating - * higher priority. It is recommended to choose priorities between - * %G_PRIORITY_LOW and %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT as a - * default. + * cases to determine the order in which operations are executed. + * They are not used to determine system-wide I/O scheduling. + * Priorities are integers, with lower numbers indicating higher priority. + * It is recommended to choose priorities between %G_PRIORITY_LOW and + * %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT as a default. **/ typedef GAsyncResultIface GAsyncResultInterface; diff --git a/gio/gcancellable.c b/gio/gcancellable.c index a6ef4ef..90d2676 100644 --- a/gio/gcancellable.c +++ b/gio/gcancellable.c @@ -90,16 +90,14 @@ g_cancellable_class_init (GCancellableClass *klass) * * Note that disconnecting from this signal (or any signal) in a * multi-threaded program is prone to race conditions. For instance - * it is possible that a signal handler may be invoked even - * after a call to - * g_signal_handler_disconnect() for that handler has already - * returned. + * it is possible that a signal handler may be invoked even after + * a call to g_signal_handler_disconnect() for that handler has + * already returned. * - * There is also a problem when cancellation happen - * right before connecting to the signal. If this happens the - * signal will unexpectedly not be emitted, and checking before - * connecting to the signal leaves a race condition where this is - * still happening. + * There is also a problem when cancellation happens right before + * connecting to the signal. If this happens the signal will + * unexpectedly not be emitted, and checking before connecting to + * the signal leaves a race condition where this is still happening. * * In order to make it safe and easy to connect handlers there * are two helper functions: g_cancellable_connect() and diff --git a/gio/gdatainputstream.c b/gio/gdatainputstream.c index 0919cdd..0a125a8 100644 --- a/gio/gdatainputstream.c +++ b/gio/gdatainputstream.c @@ -1303,8 +1303,8 @@ g_data_input_stream_read_until_finish (GDataInputStream *stream, * occurrence of any of the stop characters. * * In contrast to g_data_input_stream_read_until(), this function - * does not consume the stop character. You have - * to use g_data_input_stream_read_byte() to get it before calling + * does not consume the stop character. You have to use + * g_data_input_stream_read_byte() to get it before calling * g_data_input_stream_read_upto() again. * * 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. * * In contrast to g_data_input_stream_read_until(), this function - * does not consume the stop character. You have - * to use g_data_input_stream_read_byte() to get it before calling + * does not consume the stop character. You have to use + * g_data_input_stream_read_byte() to get it before calling * g_data_input_stream_read_upto() again. * * 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 * g_data_input_stream_read_upto_async(). * - * Note that this function does not consume the - * stop character. You have to use g_data_input_stream_read_byte() to - * get it before calling g_data_input_stream_read_upto_async() again. + * Note that this function does not consume the stop character. You + * have to use g_data_input_stream_read_byte() to get it before calling + * g_data_input_stream_read_upto_async() again. * * Returns: (transfer full): a string with the data that was read * before encountering any of the stop characters. Set @length to diff --git a/gio/gdbusconnection.c b/gio/gdbusconnection.c index e373579..8c964d2 100644 --- a/gio/gdbusconnection.c +++ b/gio/gdbusconnection.c @@ -5110,10 +5110,9 @@ obj_message_func (GDBusConnection *connection, * * GDBus automatically implements the standard D-Bus interfaces * org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable - * and org.freedesktop.Peer, so you don't have to implement those for - * the objects you export. You can implement - * org.freedesktop.DBus.Properties yourself, e.g. to handle getting - * and setting of properties asynchronously. + * and org.freedesktop.Peer, so you don't have to implement those for the + * objects you export. You can implement org.freedesktop.DBus.Properties + * yourself, e.g. to handle getting and setting of properties asynchronously. * * Note that the reference count on @interface_info will be * incremented by 1 (unless allocated statically, e.g. if the diff --git a/gio/gdbusmethodinvocation.c b/gio/gdbusmethodinvocation.c index cde3303..8f32f8d 100644 --- a/gio/gdbusmethodinvocation.c +++ b/gio/gdbusmethodinvocation.c @@ -580,7 +580,7 @@ g_dbus_method_invocation_return_value_with_unix_fd_list (GDBusMethodInvocation * * applications using GDBus. * * If you are writing an application intended to be portable, - * always 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(). * * This method will free @invocation, you cannot use it afterwards. diff --git a/gio/gdbusobjectmanagerclient.c b/gio/gdbusobjectmanagerclient.c index cb9d38f..f114ce4 100644 --- a/gio/gdbusobjectmanagerclient.c +++ b/gio/gdbusobjectmanagerclient.c @@ -91,13 +91,12 @@ * * Ultimately, #GDBusObjectManagerClient is used to obtain #GDBusProxy * instances. All signals (including the - * org.freedesktop.DBus.Properties::PropertiesChanged - * signal) delivered to #GDBusProxy instances are guaranteed to - * originate from the name owner. This guarantee along with the - * behavior described above, means that certain race conditions - * including the half the proxy is from the old owner - * and the other half is from the new owner problem - * cannot happen. + * org.freedesktop.DBus.Properties::PropertiesChanged signal) + * delivered to #GDBusProxy instances are guaranteed to originate + * from the name owner. This guarantee along with the behavior + * described above, means that certain race conditions including the + * "half the proxy is from the old owner and the other half is from + * the new owner" problem cannot happen. * * To avoid having the application connect to signals on the returned * #GDBusObjectProxy and #GDBusProxy objects, the diff --git a/gio/gdbusproxy.c b/gio/gdbusproxy.c index 95b2feb..c411c7c 100644 --- a/gio/gdbusproxy.c +++ b/gio/gdbusproxy.c @@ -361,7 +361,7 @@ g_dbus_proxy_class_init (GDBusProxyClass *klass) * Ensure that interactions with this proxy conform to the given * interface. This is mainly to ensure that malformed data received * from the other peer is ignored. The given #GDBusInterfaceInfo is - * said to be the expected interface. + * said to be the "expected interface". * * The checks performed are: * diff --git a/gio/gdbusutils.c b/gio/gdbusutils.c index 28ac518..aa92e8d 100644 --- a/gio/gdbusutils.c +++ b/gio/gdbusutils.c @@ -562,10 +562,9 @@ g_dbus_gvariant_to_gvalue (GVariant *value, * #G_TYPE_BOXED derived-types) not in the table above. * * Note that if @gvalue is of type #G_TYPE_VARIANT and its value is - * %NULL, the empty #GVariant instance (never - * %NULL) for @type is returned (e.g. 0 for scalar types, the empty - * string for string types, '/' for object path - * types, the empty array for any array type and so on). + * %NULL, the empty #GVariant instance (never %NULL) for @type is + * returned (e.g. 0 for scalar types, the empty string for string types, + * '/' for object path types, the empty array for any array type and so on). * * See the g_dbus_gvariant_to_gvalue() function for how to convert a * #GVariant to a #GValue. diff --git a/gio/gnetworking.c b/gio/gnetworking.c index 17eda38..3b41ba7 100644 --- a/gio/gnetworking.c +++ b/gio/gnetworking.c @@ -41,11 +41,10 @@ * want your code to work under both UNIX and Windows, you will need * to take these differences into account. * - * Also, under glibc, certain non-portable functions are only visible - * in the headers if you define _GNU_SOURCE before - * including them. Note that this symbol must be defined before - * including any headers, or it may not take - * effect. + * Also, under GNU libc, certain non-portable functions are only visible + * in the headers if you define %_GNU_SOURCE before including them. Note + * that this symbol must be defined before including any headers, or it + * may not take effect. */ /** diff --git a/gio/gnetworkmonitor.c b/gio/gnetworkmonitor.c index 30233d2..d74bfa4 100644 --- a/gio/gnetworkmonitor.c +++ b/gio/gnetworkmonitor.c @@ -262,10 +262,9 @@ g_network_monitor_default_init (GNetworkMonitorInterface *iface) * connected to a functioning router that has lost its own upstream * connectivity. Some hosts might only be accessible when a VPN is * active. Other hosts might only be accessible when the VPN is - * not active. Thus, it is best to use - * g_network_monitor_can_reach() or - * g_network_monitor_can_reach_async() to test for reachability on a - * host-by-host basis. (On the other hand, when the property is + * not active. Thus, it is best to use g_network_monitor_can_reach() + * or g_network_monitor_can_reach_async() to test for reachability + * on a host-by-host basis. (On the other hand, when the property is * %FALSE, the application can reasonably expect that no remote * hosts at all are reachable, and should indicate this to the user * in its UI.) diff --git a/gio/goutputstream.c b/gio/goutputstream.c index a94f4c2..adae223 100644 --- a/gio/goutputstream.c +++ b/gio/goutputstream.c @@ -399,13 +399,12 @@ g_output_stream_vprintf (GOutputStream *stream, * bindings or in other cases where the refcounted nature of #GBytes * is helpful over a bare pointer interface. * - * However, note that this function may still - * perform partial writes, just like g_output_stream_write(). If that - * occurs, to continue writing, you will need to create a new #GBytes - * containing just the remaining bytes, using - * g_bytes_new_from_bytes(). Passing the same #GBytes instance - * multiple times potentially can result in duplicated data in the - * output stream. + * However, note that this function may still perform partial writes, + * just like g_output_stream_write(). If that occurs, to continue + * writing, you will need to create a new #GBytes containing just the + * remaining bytes, using g_bytes_new_from_bytes(). Passing the same + * #GBytes instance multiple times potentially can result in duplicated + * data in the output stream. * * 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, * this allows the stream to avoid taking a copy of the data. * - * However, note that this function may still - * perform partial writes, just like g_output_stream_write_async(). - * If that occurs, to continue writing, you will need to create a new - * #GBytes containing just the remaining bytes, using - * g_bytes_new_from_bytes(). Passing the same #GBytes instance - * multiple times potentially can result in duplicated data in the - * output stream. + * However, note that this function may still perform partial writes, + * just like g_output_stream_write_async(). If that occurs, to continue + * writing, you will need to create a new #GBytes containing just the + * remaining bytes, using g_bytes_new_from_bytes(). Passing the same + * #GBytes instance multiple times potentially can result in duplicated + * data in the output stream. * * For the synchronous, blocking version of this function, see * g_output_stream_write_bytes(). diff --git a/gio/gresolver.c b/gio/gresolver.c index 11f0196..86843c6 100644 --- a/gio/gresolver.c +++ b/gio/gresolver.c @@ -595,9 +595,8 @@ g_resolver_get_service_rrname (const char *service, * Synchronously performs a DNS SRV lookup for the given @service and * @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 - * @service and @protocol arguments do not - * include the leading underscore that appears in the actual DNS - * entry. + * @service and @protocol arguments do not include the leading underscore + * that appears in the actual DNS entry. * * On success, g_resolver_lookup_service() will return a #GList of * #GSrvTarget, sorted in order of preference. (That is, you should diff --git a/gio/gsettings.c b/gio/gsettings.c index effa9fc..789870c 100644 --- a/gio/gsettings.c +++ b/gio/gsettings.c @@ -2850,8 +2850,7 @@ g_settings_binding_writable_changed (GSettings *settings, * * When the @inverted argument is %TRUE, the binding inverts the * value as it passes from the setting to the object, i.e. @property - * will be set to %TRUE if the key is not - * writable. + * will be set to %TRUE if the key is not writable. * * Note that the lifecycle of the binding is tied to the object, * and that you can have only one binding per object property. diff --git a/gio/gtask.c b/gio/gtask.c index 390e093..f56532d 100644 --- a/gio/gtask.c +++ b/gio/gtask.c @@ -1190,8 +1190,8 @@ g_task_return (GTask *task, * g_task_set_return_on_cancel() for more details. * * Other than in that case, @task will be completed when the - * #GTaskThreadFunc returns, not when it calls - * a g_task_return_ function. + * #GTaskThreadFunc returns, not when it calls a + * g_task_return_ function. * * Since: 2.36 */ diff --git a/glib/docs.c b/glib/docs.c index c73dfc2..03ca2ea 100644 --- a/glib/docs.c +++ b/glib/docs.c @@ -737,7 +737,7 @@ * p = (void*) 42; * i = (int) p; * ]| - * Again, that example was not 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: * |[ * gpointer p; @@ -761,9 +761,9 @@ * Stuffs an integer into a pointer type. * * Remember, you may not store pointers in integers. This is not portable - * in any way, shape or form. These macros only allow - * storing integers in pointers, and only preserve 32 bits of the - * integer; values outside the range of a 32-bit integer will be mangled. + * in any way, shape or form. These macros only allow storing integers in + * pointers, and only preserve 32 bits of the integer; values outside the + * range of a 32-bit integer will be mangled. */ /** @@ -774,9 +774,9 @@ * been stored in the pointer with GINT_TO_POINTER(). * * Remember, you may not store pointers in integers. This is not portable - * in any way, shape or form. These macros only allow - * storing integers in pointers, and only preserve 32 bits of the - * integer; values outside the range of a 32-bit integer will be mangled. + * in any way, shape or form. These macros only allow storing integers in + * pointers, and only preserve 32 bits of the integer; values outside the + * range of a 32-bit integer will be mangled. */ /** @@ -1679,19 +1679,17 @@ /** * G_CONST_RETURN: * - * If G_DISABLE_CONST_RETURNS is defined, this macro expands - * to nothing. By default, the macro expands to const. - * The macro should be used in place of const for - * functions that return a value that should not be modified. The - * purpose of this macro is to allow us to turn on const - * for returned constant strings by default, while allowing programmers - * who find that annoying to turn it off. This macro should only be used - * for return values and for out parameters, it doesn't - * make sense for in parameters. + * If %G_DISABLE_CONST_RETURNS is defined, this macro expands + * to nothing. By default, the macro expands to const. The macro + * can be used in place of const for functions that return a value + * that should not be modified. The purpose of this macro is to allow + * us to turn on const for returned constant strings by default, while + * allowing programmers who find that annoying to turn it off. This macro + * should only be used for return values and for "out" parameters, it + * doesn't make sense for "in" parameters. * * Deprecated: 2.30: API providers should replace all existing uses with - * const and API consumers should adjust their code - * accordingly + * const and API consumers should adjust their code accordingly */ /** diff --git a/glib/gcharset.c b/glib/gcharset.c index 1611187..82e3fc6 100644 --- a/glib/gcharset.c +++ b/glib/gcharset.c @@ -438,7 +438,7 @@ append_locale_variants (GPtrArray *array, * For example, if @locale is "fr_BE", then the returned list * is "fr_BE", "fr". * - * If you need the list of variants for the current locale, + * If you need the list of variants for the current locale, * use g_get_language_names(). * * Returns: (transfer full) (array zero-terminated=1) (element-type utf8): a newly diff --git a/glib/gconvert.c b/glib/gconvert.c index 19c872a..df69bb2 100644 --- a/glib/gconvert.c +++ b/glib/gconvert.c @@ -98,12 +98,11 @@ * 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(), * and you wish to display the file name to the user, you - * will need to convert it into UTF-8. The - * opposite case is when the user types the name of a file he - * wishes to save: the toolkit will give you that string in - * UTF-8 encoding, and you will need to convert it to the - * character set used for file names before you can create the - * file with open(2) or fopen(3). + * will need to convert it into UTF-8. The opposite case is when the + * user types the name of a file he wishes to save: the toolkit will + * give you that string in UTF-8 encoding, and you will need to convert + * it to the character set used for file names before you can create the + * file with open() or fopen(). * * * By default, Glib assumes that file names on disk are in UTF-8 @@ -157,9 +156,9 @@ * * 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 - * "Unknown file name". Do not - * convert this string back into the encoding used for file names if you - * wish to pass it to the file system; use the original file name instead. + * "Unknown file name". Do not convert this string back into the encoding + * used for file names if you wish to pass it to the file system; use the + * original file name instead. * 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 * file, as it would keep the raw file name internally. This can happen diff --git a/glib/gdate.c b/glib/gdate.c index a2db8ad..375e4e4 100644 --- a/glib/gdate.c +++ b/glib/gdate.c @@ -69,7 +69,7 @@ * or ISO timestamps or the like. It extrapolates the current Gregorian * calendar forward and backward in time; there is no attempt to change * the calendar to match time periods or locations. #GDate does not store - * time information; it represents a day. + * time information; it represents a day. * * The #GDate implementation has several nice features; it is only a * 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 * g_date_set_dmy() and the other mutator functions to initialize the * value of a cleared date. However, a cleared date is initially - * invalid, meaning that it doesn't represent a day - * that exists. It is undefined to call any of the date calculation - * routines on an invalid date. If you obtain a date from a user or other + * invalid, meaning that it doesn't represent a day that exists. + * It is undefined to call any of the date calculation routines on an + * invalid date. If you obtain a date from a user or other * unpredictable source, you should check its validity with the * g_date_valid() predicate. g_date_valid() is also used to check for * errors with g_date_set_parse() and other functions that can * fail. Dates can be invalidated by calling g_date_clear() again. * - * It is very important to use the API to access the #GDate - * struct. Often only the day-month-year or only the Julian + * It is very important to use the API to access the #GDate + * struct. Often only the day-month-year or only the Julian * representation is valid. Sometimes neither is valid. Use the API. * * GLib also features #GDateTime which represents a precise time. @@ -151,11 +151,11 @@ * GTime: * * Simply a replacement for time_t. It has been deprecated - * since it is not equivalent to time_t - * on 64-bit platforms with a 64-bit time_t. Unrelated to #GTimer. + * since it is not equivalent to time_t on 64-bit platforms + * with a 64-bit time_t. Unrelated to #GTimer. * - * Note that #GTime is defined to always be a 32bit integer, - * unlike time_t which may be 64bit on some systems. Therefore, + * Note that #GTime is defined to always be a 32-bit integer, + * unlike time_t which may be 64-bit on some systems. Therefore, * #GTime will overflow in the year 2038, and you cannot use the * address of a #GTime variable as argument to the UNIX time() * function. @@ -183,8 +183,8 @@ /** * GDateDay: * - * Integer representing a day of the month; between 1 and - * 31. #G_DATE_BAD_DAY represents an invalid day of the month. + * Integer representing a day of the month; between 1 and 31. + * #G_DATE_BAD_DAY represents an invalid day of the month. */ /** diff --git a/glib/gerror.c b/glib/gerror.c index 438d158..d978a93 100644 --- a/glib/gerror.c +++ b/glib/gerror.c @@ -30,18 +30,18 @@ * GLib provides a standard method of reporting errors from a called * function to the calling code. (This is the same problem solved by * exceptions in other languages.) It's important to understand that - * this method is both a data type (the #GError - * object) and a set of rules. If you use #GError - * incorrectly, then your code will not properly interoperate with other - * code that uses #GError, and users of your API will probably get confused. - * - * First and foremost: #GError should only be used to report - * recoverable runtime errors, never to report programming - * errors. If the programmer has screwed up, then you should - * use g_warning(), g_return_if_fail(), g_assert(), g_error(), or some - * similar facility. (Incidentally, remember that the g_error() function - * should only be used for programming errors, it - * should not be used to print any error reportable via #GError.) + * this method is both a data type (the #GError struct) and a set of + * rules. If you use #GError incorrectly, then your code will not + * properly interoperate with other code that uses #GError, and users + * of your API will probably get confused. + * + * First and foremost: #GError should only be used to report recoverable + * runtime errors, never to report programming errors. If the programmer + * has screwed up, then you should use g_warning(), g_return_if_fail(), + * g_assert(), g_error(), or some similar facility. (Incidentally, + * remember that the g_error() function should only be used for + * programming errors, it should not be used to print any error + * reportable via #GError.) * * Examples of recoverable runtime errors are "file not found" or * "failed to parse input." Examples of programming errors are "NULL @@ -81,14 +81,13 @@ * } * ]| * Note that err != NULL in this example is a - * reliable indicator of whether - * g_file_get_contents() failed. Additionally, g_file_get_contents() - * returns a boolean which indicates whether it was successful. + * reliable indicator of whether g_file_get_contents() failed. + * Additionally, g_file_get_contents() returns a boolean which + * indicates whether it was successful. * * Because g_file_get_contents() returns %FALSE on failure, if you * are only interested in whether it failed and don't need to display - * an error message, you can pass %NULL for the error - * argument: + * an error message, you can pass %NULL for the @error argument: * |[ * if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) /* ignore errors */ * /* no error occurred */ ; @@ -96,21 +95,19 @@ * /* error */ ; * ]| * - * The #GError object contains three fields: domain - * indicates the module the error-reporting function is located in, - * code indicates the specific error that occurred, - * and message is a user-readable error message with + * The #GError object contains three fields: @domain indicates the module + * the error-reporting function is located in, @code indicates the specific + * error that occurred, and @message is a user-readable error message with * as many details as possible. Several functions are provided to deal * with an error received from a called function: g_error_matches() * returns %TRUE if the error matches a given domain and code, * g_propagate_error() copies an error into an error location (so the * calling function will receive it), and g_clear_error() clears an * error location by freeing the error and resetting the location to - * %NULL. To display an error to the user, simply display - * error->message, perhaps along with additional - * context known only to the calling function (the file being opened, - * or whatever -- though in the g_file_get_contents() case, - * error->message already contains a filename). + * %NULL. To display an error to the user, simply display the @message, + * perhaps along with additional context known only to the calling + * function (the file being opened, or whatever - though in the + * g_file_get_contents() case, the @message already contains a filename). * * When implementing a function that can report errors, the basic * tool is g_set_error(). Typically, if a fatal error occurs you @@ -209,10 +206,10 @@ * } * } * ]| - * tmp_error should be checked immediately after - * sub_function_that_can_fail(), and either cleared or propagated - * upward. The rule is: after each error, you must either - * handle the error, or return it to the calling function. + * @tmp_error should be checked immediately after sub_function_that_can_fail(), + * and either cleared or propagated upward. The rule is: after each error, + * you must either handle the error, or return it to the calling function. + * * Note that passing %NULL for the error location is the equivalent * of handling an error by always doing nothing about it. So the * following code is fine, assuming errors in sub_function_that_can_fail() @@ -238,11 +235,11 @@ * } * ]| * - * Note that passing %NULL for the error location - * ignores errors; it's equivalent to + * Note that passing %NULL for the error location ignores errors; it's + * equivalent to * try { sub_function_that_can_fail (); } catch (...) {} - * in C++. It does not mean to leave errors - * unhandled; it means to handle them by doing nothing. + * in C++. It does not mean to leave errors unhandled; it means to + * handle them by doing nothing. * * Error domains and codes are conventionally named as follows: * @@ -305,12 +302,11 @@ * not be affected by whether the caller wants to get a #GError. * * - * If a #GError is reported, then your function by definition - * had a fatal failure and did not complete whatever - * it was supposed to do. If the failure was not fatal, - * then you handled it and you should not report it. If it was fatal, - * then you must report it and discontinue whatever you were doing - * immediately. + * If a #GError is reported, then your function by definition had a + * fatal failure and did not complete whatever it was supposed to do. + * If the failure was not fatal, then you handled it and you should not + * report it. If it was fatal, then you must report it and discontinue + * whatever you were doing immediately. * * * If a #GError is reported, out parameters are not guaranteed to @@ -331,7 +327,7 @@ * * By convention, if you return a boolean value indicating success * then %TRUE means success and %FALSE means failure. If %FALSE is - * returned, the error must be set to a non-%NULL + * returned, the error must be set to a non-%NULL * value. * * @@ -668,16 +664,13 @@ g_error_add_prefix (gchar **string, * @format: printf()-style format string * @...: arguments to @format * - * Formats a string according to @format and - * prefix it to an existing error message. If - * @err is %NULL (ie: no error variable) then do + * Formats a string according to @format and prefix it to an existing + * error message. If @err is %NULL (ie: no error variable) then do * nothing. * - * If *@err is %NULL (ie: an error variable is - * present but there is no error condition) then - * also do nothing. Whether or not it makes - * sense to take advantage of this feature is up - * to you. + * If *@err is %NULL (ie: an error variable is present but there is no + * error condition) then also do nothing. Whether or not it makes sense + * to take advantage of this feature is up to you. * * Since: 2.16 */ @@ -703,9 +696,8 @@ g_prefix_error (GError **err, * @format: printf()-style format string * @...: arguments to @format * - * If @dest is %NULL, free @src; otherwise, - * moves @src into *@dest. *@dest must be %NULL. - * After the move, add a prefix as with + * If @dest is %NULL, free @src; otherwise, moves @src into *@dest. + * *@dest must be %NULL. After the move, add a prefix as with * g_prefix_error(). * * Since: 2.16 diff --git a/glib/ggettext.c b/glib/ggettext.c index bd5c9d4..759b067 100644 --- a/glib/ggettext.c +++ b/glib/ggettext.c @@ -472,8 +472,8 @@ g_dngettext (const gchar *domain, * * In order to use these macros in an application, you must include * glib/gi18n.h. For use in a library, you must include - * glib/gi18n-lib.h after defining - * the GETTEXT_PACKAGE macro suitably for your library: + * glib/gi18n-lib.h after defining the %GETTEXT_PACKAGE + * macro suitably for your library: * |[ * #define GETTEXT_PACKAGE "gtk20" * #include <glib/gi18n-lib.h> diff --git a/glib/giochannel.c b/glib/giochannel.c index 33a3c94..7d43292 100644 --- a/glib/giochannel.c +++ b/glib/giochannel.c @@ -1317,8 +1317,7 @@ g_io_channel_get_buffered (GIOChannel *channel) * %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. * Returning one of these statuses from g_io_channel_read_line(), * g_io_channel_read_line_string(), or g_io_channel_read_to_end() - * does not guarantee that the encoding can - * be changed. + * does not guarantee that the encoding can be changed. * * * Channels which do not meet one of the above conditions cannot call diff --git a/glib/gmain.c b/glib/gmain.c index 1ff5db4..d4f1282 100644 --- a/glib/gmain.c +++ b/glib/gmain.c @@ -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 * results to its main loop, rather than running under the global * default context in the main thread. Note that calling this function - * changes the context returned by - * g_main_context_get_thread_default(), not the - * one returned by g_main_context_default(), so it does not affect the - * context used by functions like g_idle_add(). + * changes the context returned by g_main_context_get_thread_default(), + * not the one returned by g_main_context_default(), so it does not affect + * the context used by functions like g_idle_add(). * * Normally you would call this function shortly after creating a new * thread, passing it a #GMainContext which will be run by a diff --git a/glib/gmem.c b/glib/gmem.c index 980cc09..c17dda4 100644 --- a/glib/gmem.c +++ b/glib/gmem.c @@ -493,13 +493,17 @@ g_mem_is_system_malloc (void) * g_mem_set_vtable: * @vtable: table of memory allocation routines. * - * Sets the #GMemVTable to use for memory allocation. You can use this to provide - * custom memory allocation routines. This function must be called - * before using any other GLib functions. The @vtable only needs to - * provide malloc(), realloc(), and free() functions; GLib can provide default - * implementations of the others. The malloc() and realloc() implementations - * should return %NULL on failure, GLib will handle error-checking for you. - * @vtable is copied, so need not persist after this function has been called. + * Sets the #GMemVTable to use for memory allocation. You can use this + * to provide custom memory allocation routines. + * + * The @vtable only needs to provide malloc(), realloc(), and free() + * functions; GLib can provide default implementations of the others. + * The malloc() and realloc() implementations should return %NULL on + * 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 g_mem_set_vtable (GMemVTable *vtable) diff --git a/glib/gmessages.c b/glib/gmessages.c index 60eaab0..2509f7b 100644 --- a/glib/gmessages.c +++ b/glib/gmessages.c @@ -553,8 +553,7 @@ g_log_set_fatal_mask (const gchar *log_domain, * * * - * Adding a log handler for <emphasis>all</emphasis> messages from - * GLib + * Adding a log handler for all messages from GLib * * g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL * | G_LOG_FLAG_RECURSION, my_log_handler, NULL); diff --git a/glib/goption.c b/glib/goption.c index db71037..64e170a 100644 --- a/glib/goption.c +++ b/glib/goption.c @@ -2199,11 +2199,11 @@ g_option_group_new (const gchar *name, * g_option_group_free: * @group: a #GOptionGroup * - * Frees a #GOptionGroup. Note that you must not - * free groups which have been added to a #GOptionContext. + * Frees a #GOptionGroup. Note that you must not free groups + * which have been added to a #GOptionContext. * * Since: 2.6 - **/ + */ void g_option_group_free (GOptionGroup *group) { diff --git a/glib/gpattern.c b/glib/gpattern.c index be5951d..4894c28 100644 --- a/glib/gpattern.c +++ b/glib/gpattern.c @@ -38,11 +38,9 @@ * semantics as the standard glob() function: '*' matches an arbitrary, * possibly empty, string, '?' matches an arbitrary character. * - * Note that in contrast to glob(), the '/' character - * can be matched by the wildcards, there are no - * '[...]' character ranges and '*' and '?' can - * not be escaped to include them literally in a - * pattern. + * Note that in contrast to glob(), the '/' character can be matched by + * the wildcards, there are no '[...]' character ranges and '*' and '?' can + * not be escaped to include them literally in a pattern. * * When multiple strings must be matched against the same pattern, it * 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: * @pspec: a #GPatternSpec * @string_length: the length of @string (in bytes, i.e. strlen(), - * not g_utf8_strlen()) + * not g_utf8_strlen()) * @string: the UTF-8 encoded string to match * @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(). * * Note also that the reverse of a UTF-8 encoded string can in general - * not be obtained by g_strreverse(). This works - * only if the string doesn't contain any multibyte characters. GLib - * offers the g_utf8_strreverse() function to reverse UTF-8 encoded - * strings. + * not be obtained by g_strreverse(). This works only if the string + * does not contain any multibyte characters. GLib offers the + * g_utf8_strreverse() function to reverse UTF-8 encoded strings. * * Returns: %TRUE if @string matches @pspec **/ diff --git a/glib/gquark.c b/glib/gquark.c index c9750df..868b685 100644 --- a/glib/gquark.c +++ b/glib/gquark.c @@ -57,7 +57,7 @@ static gint quark_block_offset = 0; * SECTION:quarks * @title: Quarks * @short_description: a 2-way association between a string and a - * unique integer identifier + * unique integer identifier * * Quarks are associations between strings and integer identifiers. * Given either the string or the #GQuark identifier it is possible to @@ -82,14 +82,14 @@ static gint quark_block_offset = 0; * representation for a string. One important advantage of interned * strings is that they can be compared for equality by a simple * pointer comparison, rather than using strcmp(). - **/ + */ /** * GQuark: * * A GQuark is a non-zero integer which uniquely identifies a * particular string. A GQuark value of zero is associated to %NULL. - **/ + */ /** * G_DEFINE_QUARK: @@ -99,24 +99,26 @@ static gint quark_block_offset = 0; * A convenience macro which defines a function returning the * #GQuark for the name @QN. The function will be named * @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 */ /** * g_quark_try_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. + * @string: (allow-none): a string * * Gets the #GQuark associated with the given string, or 0 if string is * %NULL or it has no associated #GQuark. * * 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(). - **/ + * + * Returns: the #GQuark associated with the string, or 0 if @string is + * %NULL or there is no #GQuark associated with it + */ GQuark g_quark_try_string (const gchar *string) { @@ -182,14 +184,13 @@ quark_from_string (const gchar *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 * not currently have an associated #GQuark, a new #GQuark is created, * using a copy of the string. * - * Returns: the #GQuark identifying the string, or 0 if @string is - * %NULL. + * Returns: the #GQuark identifying the string, or 0 if @string is %NULL */ GQuark g_quark_from_string (const gchar *string) @@ -208,7 +209,7 @@ g_quark_from_string (const gchar *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 * 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 * 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 - * will always exist. It can be used with - * statically allocated strings in the main program, but not with + * will continue to exist until the program terminates. It can be used + * with statically allocated strings in the main program, but not with * statically allocated memory in dynamically loaded modules, if you * expect to ever unload the module again (e.g. do not use this * function in GTK+ theme engines). * - * Returns: the #GQuark identifying the string, or 0 if @string is - * %NULL. + * Returns: the #GQuark identifying the string, or 0 if @string is %NULL */ GQuark g_quark_from_static_string (const gchar *string) diff --git a/glib/gqueue.c b/glib/gqueue.c index 926539c..bc27ff8 100644 --- a/glib/gqueue.c +++ b/glib/gqueue.c @@ -375,8 +375,7 @@ g_queue_push_nth (GQueue *queue, /** * g_queue_push_head_link: * @queue: a #GQueue - * @link_: a single #GList element, not a list with - * more than one element + * @link_: a single #GList element, not a list with more than one element * * 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: * @queue: a #GQueue - * @link_: a single #GList element, not a list with - * more than one element + * @link_: a single #GList element, not a list with more than one element * * Adds a new element at the tail of the queue. */ @@ -791,10 +789,10 @@ g_queue_link_index (GQueue *queue, /** * g_queue_unlink: * @queue: a #GQueue - * @link_: a #GList link that must 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 - * not freed. + * Unlinks @link_ so that it will no longer be part of @queue. + * The link is not freed. * * @link_ must be part of @queue. * @@ -817,7 +815,7 @@ g_queue_unlink (GQueue *queue, /** * g_queue_delete_link: * @queue: a #GQueue - * @link_: a #GList link that must be part of @queue + * @link_: a #GList link that must be part of @queue * * Removes @link_ from @queue and frees it. * @@ -985,7 +983,7 @@ g_queue_remove_all (GQueue *queue, /** * g_queue_insert_before: * @queue: a #GQueue - * @sibling: a #GList link that must be part of @queue + * @sibling: a #GList link that must be part of @queue * @data: the data to insert * * Inserts @data into @queue before @sibling. @@ -1009,7 +1007,7 @@ g_queue_insert_before (GQueue *queue, /** * g_queue_insert_after: * @queue: a #GQueue - * @sibling: a #GList link that must be part of @queue + * @sibling: a #GList link that must be part of @queue * @data: the data to insert * * Inserts @data into @queue after @sibling diff --git a/glib/gsequence.c b/glib/gsequence.c index 9f65b5f..afa475b 100644 --- a/glib/gsequence.c +++ b/glib/gsequence.c @@ -63,14 +63,14 @@ * g_sequence_move_range() will not invalidate the iterators pointing * to it. The only operation that will invalidate an iterator is when * the element it points to is removed from any sequence. - **/ + */ /** * GSequenceIter: * * The #GSequenceIter struct is an opaque data type representing an * iterator pointing into a #GSequence. - **/ + */ /** * GSequenceIterCompareFunc: @@ -83,9 +83,8 @@ * 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 - * comes before @b, and a positive value if @b comes before - * @a. - **/ + * comes before @b, and a positive value if @b comes before @a. + */ typedef struct _GSequenceNode GSequenceNode; @@ -94,7 +93,7 @@ typedef struct _GSequenceNode GSequenceNode; * * The #GSequence struct is an opaque data type representing a * Sequence data type. - **/ + */ struct _GSequence { GSequenceNode * end_node; @@ -268,11 +267,11 @@ g_sequence_new (GDestroyNotify data_destroy) * @seq: a #GSequence * * Frees the memory allocated for @seq. If @seq has a data destroy - * function associated with it, that function is called on all items in - * @seq. + * function associated with it, that function is called on all items + * in @seq. * * Since: 2.14 - **/ + */ void g_sequence_free (GSequence *seq) { @@ -296,7 +295,7 @@ g_sequence_free (GSequence *seq) * @user_data to the function. * * Since: 2.14 - **/ + */ void g_sequence_foreach_range (GSequenceIter *begin, GSequenceIter *end, @@ -337,7 +336,7 @@ g_sequence_foreach_range (GSequenceIter *begin, * to the function. * * Since: 2.14 - **/ + */ void g_sequence_foreach (GSequence *seq, GFunc func, @@ -360,16 +359,16 @@ g_sequence_foreach (GSequence *seq, * * Finds an iterator somewhere in the range (@begin, @end). This * iterator will be close to the middle of the range, but is not - * guaranteed to be exactly in the middle. + * guaranteed to be exactly in the middle. * - * The @begin and @end iterators must both point to the same sequence and - * @begin must come before or be equal to @end in the sequence. + * The @begin and @end iterators must both point to the same sequence + * and @begin must come before or be equal to @end in the sequence. * - * Return value: A #GSequenceIter pointing somewhere in the - * (@begin, @end) range. + * Return value: a #GSequenceIter pointing somewhere in the + * (@begin, @end) range * * Since: 2.14 - **/ + */ GSequenceIter * g_sequence_range_get_midpoint (GSequenceIter *begin, GSequenceIter *end) @@ -400,11 +399,11 @@ g_sequence_range_get_midpoint (GSequenceIter *begin, * * 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 - * equal, and a positive number if @a comes after @b. + * Return value: a negative number if @a comes before @b, 0 if they are + * equal, and a positive number if @a comes after @b * * Since: 2.14 - **/ + */ gint g_sequence_iter_compare (GSequenceIter *a, GSequenceIter *b) @@ -439,7 +438,7 @@ g_sequence_iter_compare (GSequenceIter *a, * Return value: an iterator pointing to the new item * * Since: 2.14 - **/ + */ GSequenceIter * g_sequence_append (GSequence *seq, gpointer data) @@ -466,7 +465,7 @@ g_sequence_append (GSequence *seq, * Return value: an iterator pointing to the new item * * Since: 2.14 - **/ + */ GSequenceIter * g_sequence_prepend (GSequence *seq, gpointer data) @@ -495,7 +494,7 @@ g_sequence_prepend (GSequence *seq, * Return value: an iterator pointing to the new item * * Since: 2.14 - **/ + */ GSequenceIter * g_sequence_insert_before (GSequenceIter *iter, gpointer data) @@ -524,7 +523,7 @@ g_sequence_insert_before (GSequenceIter *iter, * function is called on the data for the removed item. * * Since: 2.14 - **/ + */ void g_sequence_remove (GSequenceIter *iter) { @@ -552,7 +551,7 @@ g_sequence_remove (GSequenceIter *iter) * function is called on the data for the removed items. * * Since: 2.14 - **/ + */ void g_sequence_remove_range (GSequenceIter *begin, GSequenceIter *end) @@ -581,7 +580,7 @@ g_sequence_remove_range (GSequenceIter *begin, * the (@begin, @end) range, the range does not move. * * Since: 2.14 - **/ + */ void g_sequence_move_range (GSequenceIter *dest, GSequenceIter *begin, @@ -660,7 +659,7 @@ g_sequence_move_range (GSequenceIter *dest, * if the second comes before the first. * * Since: 2.14 - **/ + */ void g_sequence_sort (GSequence *seq, GCompareDataFunc cmp_func, @@ -696,7 +695,7 @@ g_sequence_sort (GSequence *seq, * Return value: a #GSequenceIter pointing to the new item. * * Since: 2.14 - **/ + */ GSequenceIter * g_sequence_insert_sorted (GSequence *seq, gpointer data, @@ -733,7 +732,7 @@ g_sequence_insert_sorted (GSequence *seq, * the second item comes before the first. * * Since: 2.14 - **/ + */ void g_sequence_sort_changed (GSequenceIter *iter, GCompareDataFunc cmp_func, @@ -756,7 +755,7 @@ g_sequence_sort_changed (GSequenceIter *iter, * @seq: a #GSequence * @data: data for the new item * @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 * be inserted according to @cmp_func and @cmp_data. @@ -776,10 +775,10 @@ g_sequence_sort_changed (GSequenceIter *iter, * doing unsorted insertions. * * 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 - **/ + */ GSequenceIter * g_sequence_search (GSequence *seq, gpointer data, @@ -803,7 +802,7 @@ g_sequence_search (GSequence *seq, * @seq: a #GSequence * @data: data to lookup * @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 * equal to @data according to @cmp_func and @cmp_data. If more than one @@ -824,15 +823,15 @@ g_sequence_search (GSequence *seq, * * Return value: an #GSequenceIter pointing to the position of the * 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 - **/ + */ GSequenceIter * -g_sequence_lookup (GSequence *seq, - gpointer data, - GCompareDataFunc cmp_func, - gpointer cmp_data) +g_sequence_lookup (GSequence *seq, + gpointer data, + GCompareDataFunc cmp_func, + gpointer cmp_data) { SortInfo info; @@ -861,7 +860,7 @@ g_sequence_lookup (GSequence *seq, * iterator comes before the first. * * Since: 2.14 - **/ + */ void g_sequence_sort_iter (GSequence *seq, GSequenceIterCompareFunc cmp_func, @@ -916,7 +915,7 @@ g_sequence_sort_iter (GSequence *seq, * iterator comes before the first. * * Since: 2.14 - **/ + */ void g_sequence_sort_changed_iter (GSequenceIter *iter, GSequenceIterCompareFunc iter_cmp, @@ -986,7 +985,7 @@ g_sequence_sort_changed_iter (GSequenceIter *iter, * Return value: a #GSequenceIter pointing to the new item * * Since: 2.14 - **/ + */ GSequenceIter * g_sequence_insert_sorted_iter (GSequence *seq, gpointer data, @@ -1056,10 +1055,10 @@ g_sequence_insert_sorted_iter (GSequence *seq, * * Return value: a #GSequenceIter pointing to the position in @seq * where @data would have been inserted according to @iter_cmp - * and @cmp_data. + * and @cmp_data * * Since: 2.14 - **/ + */ GSequenceIter * g_sequence_search_iter (GSequence *seq, gpointer data, @@ -1114,15 +1113,15 @@ g_sequence_search_iter (GSequence *seq, * * Return value: an #GSequenceIter pointing to the position of * 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 - **/ + */ GSequenceIter * -g_sequence_lookup_iter (GSequence *seq, - gpointer data, - GSequenceIterCompareFunc iter_cmp, - gpointer cmp_data) +g_sequence_lookup_iter (GSequence *seq, + gpointer data, + GSequenceIterCompareFunc iter_cmp, + gpointer cmp_data) { GSequenceNode *node; GSequenceNode *dummy; @@ -1155,10 +1154,10 @@ g_sequence_lookup_iter (GSequence *seq, * * 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 - **/ + */ GSequence * 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 * * Since: 2.14 - **/ + */ gpointer 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. * * Since: 2.14 - **/ + */ void g_sequence_set (GSequenceIter *iter, gpointer data) @@ -1239,7 +1238,7 @@ g_sequence_set (GSequenceIter *iter, * Return value: the length of @seq * * Since: 2.14 - **/ + */ gint g_sequence_get_length (GSequence *seq) { @@ -1255,7 +1254,7 @@ g_sequence_get_length (GSequence *seq) * Return value: the end iterator for @seq * * Since: 2.14 - **/ + */ GSequenceIter * 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. * * Since: 2.14 - **/ + */ GSequenceIter * g_sequence_get_begin_iter (GSequence *seq) { @@ -1300,7 +1299,7 @@ clamp_position (GSequence *seq, /** * g_sequence_get_iter_at_pos: * @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 * 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 * * Since: 2.14 - **/ + */ GSequenceIter * g_sequence_get_iter_at_pos (GSequence *seq, gint pos) @@ -1324,7 +1323,7 @@ g_sequence_get_iter_at_pos (GSequence *seq, * g_sequence_move: * @src: a #GSequenceIter pointing to the item to move * @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. * 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 * - * Return value: Whether @iter is the end iterator. + * Return value: Whether @iter is the end iterator * * Since: 2.14 - **/ + */ gboolean 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 * * Since: 2.14 - **/ + */ gboolean g_sequence_iter_is_begin (GSequenceIter *iter) { @@ -1395,7 +1394,7 @@ g_sequence_iter_is_begin (GSequenceIter *iter) * Return value: the position of @iter * * Since: 2.14 - **/ + */ gint g_sequence_iter_get_position (GSequenceIter *iter) { @@ -1408,13 +1407,13 @@ g_sequence_iter_get_position (GSequenceIter *iter) * g_sequence_iter_next: * @iter: a #GSequenceIter * - * Returns an iterator pointing to the next position after @iter. If - * @iter is the end iterator, the end iterator is returned. + * Returns an iterator pointing to the next position after @iter. + * 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 - **/ + */ GSequenceIter * g_sequence_iter_next (GSequenceIter *iter) { @@ -1427,14 +1426,14 @@ g_sequence_iter_next (GSequenceIter *iter) * g_sequence_iter_prev: * @iter: a #GSequenceIter * - * Returns an iterator pointing to the previous position before @iter. If - * @iter is the begin iterator, the begin iterator is returned. + * Returns an iterator pointing to the previous position before @iter. + * If @iter is the begin iterator, the begin iterator is returned. * - * Return value: a #GSequenceIter pointing to the previous position before - * @iter. + * Return value: a #GSequenceIter pointing to the previous position + * before @iter * * Since: 2.14 - **/ + */ GSequenceIter * g_sequence_iter_prev (GSequenceIter *iter) { @@ -1447,17 +1446,17 @@ g_sequence_iter_prev (GSequenceIter *iter) * g_sequence_iter_move: * @iter: a #GSequenceIter * @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. * 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 * 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 - **/ + */ GSequenceIter * g_sequence_iter_move (GSequenceIter *iter, gint delta) @@ -1488,7 +1487,7 @@ g_sequence_iter_move (GSequenceIter *iter, * to point into difference sequences. * * Since: 2.14 - **/ + */ void g_sequence_swap (GSequenceIter *a, GSequenceIter *b) diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c index 4cfcf24..de48e2f 100644 --- a/glib/gstrfuncs.c +++ b/glib/gstrfuncs.c @@ -66,7 +66,7 @@ * Note that the functions g_printf(), g_fprintf(), g_sprintf(), * g_snprintf(), g_vprintf(), g_vfprintf(), g_vsprintf() and g_vsnprintf() * are declared in the header gprintf.h which is - * not included in glib.h + * not included in glib.h * (otherwise using glib.h would drag in * stdio.h), so you'll have to explicitly include * <glib/gprintf.h> in order to use the GLib @@ -75,14 +75,14 @@ * While you may use the printf() functions * to format UTF-8 strings, notice that the precision of a * %Ns parameter is interpreted as the - * number of bytes, not characters - * to print. On top of that, the GNU libc implementation of the printf() - * functions has the "feature" that it checks that the string given for - * the %Ns parameter consists of a whole number - * of characters in the current encoding. So, unless you are sure you are - * always going to be in an UTF-8 locale or your know your text is restricted - * to ASCII, avoid using %Ns. If your intention is - * to format strings for a certain number of columns, then + * number of bytes, not characters to print. On top of that, the GNU + * libc implementation of the printf() functions has the "feature" that + * it checks that the string given for the %Ns + * parameter consists of a whole number of characters in the current + * encoding. So, unless you are sure you are always going to be in an + * UTF-8 locale or your know your text is restricted to ASCII, avoid + * using %Ns. If your intention is to format + * strings for a certain number of columns, then * %Ns is not a correct solution anyway, since it * fails to take wide characters (see g_unichar_iswide()) into account. * @@ -1332,13 +1332,13 @@ g_strlcat (gchar *dest, * Portability wrapper that calls strlcpy() on systems which have it, * and emulates strlcpy() otherwise. Copies @src to @dest; @dest is * 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 - * (unless dest_size == 0). This function does not - * allocate memory. Unlike strncpy(), this function doesn't pad dest (so - * it's often faster). It returns the size of the attempted result, - * strlen (src), so if @retval >= @dest_size, truncation occurred. + * At most @dest_size - 1 characters will be copied. Always nul-terminates + * (unless @dest_size is 0). This function does not allocate memory. Unlike + * strncpy(), this function doesn't pad @dest (so it's often faster). It + * returns the size of the attempted result, strlen (src), so if + * @retval >= @dest_size, truncation occurred. * * Caveat: strlcpy() is supposedly more secure than strcpy() or strncpy(), * but if you really want to avoid screwups, g_strdup() is an even better diff --git a/glib/gthread.c b/glib/gthread.c index d410dbc..ffac638 100644 --- a/glib/gthread.c +++ b/glib/gthread.c @@ -144,10 +144,9 @@ * not automatically locked for performance reasons. For example, * you must coordinate accesses to the same #GHashTable from multiple * threads. The two notable exceptions from this rule are #GMainLoop - * and #GAsyncQueue, which are thread-safe and - * need no further application-level locking to be accessed from - * multiple threads. Most refcounting functions such as g_object_ref() - * are also thread-safe. + * and #GAsyncQueue, which are thread-safe and need no further + * application-level locking to be accessed from multiple threads. + * Most refcounting functions such as g_object_ref() are also thread-safe. */ /* G_LOCK Documentation {{{1 ---------------------------------------------- */ diff --git a/glib/gutf8.c b/glib/gutf8.c index 76acb35..b866349 100644 --- a/glib/gutf8.c +++ b/glib/gutf8.c @@ -1608,12 +1608,12 @@ fast_validate_len (const char *str, * being validated otherwise). * * 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+ - * routines require valid UTF-8 as input; - * so data read from a file or the network should be checked - * with g_utf8_validate() before doing anything else with it. + * routines require valid UTF-8 as input; so data read from a file + * or the network should be checked with g_utf8_validate() before + * doing anything else with it. * * Return value: %TRUE if the text was valid UTF-8 */ diff --git a/glib/gutils.c b/glib/gutils.c index 071471d..bc206be 100644 --- a/glib/gutils.c +++ b/glib/gutils.c @@ -1000,14 +1000,15 @@ static gchar *g_prgname = NULL; /** * g_get_prgname: * - * Gets the name of the program. This name should not - * be localized, contrast with g_get_application_name(). - * (If you are using GDK or GTK+ the program name is set in gdk_init(), + * Gets the name of the program. This name should not be localized, + * in contrast to g_get_application_name(). + * + * 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 - * the last component of argv[0].) + * the last component of @argv[0]. * * 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. */ const gchar* g_get_prgname (void) @@ -1048,9 +1049,10 @@ g_get_prgname (void) * g_set_prgname: * @prgname: the name of the program. * - * Sets the name of the program. This name should not - * be localized, contrast with g_set_application_name(). Note that for - * thread-safety reasons this function can only be called once. + * Sets the name of the program. This name should not be localized, + * in contrast to g_set_application_name(). + * + * Note that for thread-safety reasons this function can only be called once. */ void g_set_prgname (const gchar *prgname) diff --git a/gobject/gbinding.c b/gobject/gbinding.c index 7a9f562..8cf3752 100644 --- a/gobject/gbinding.c +++ b/gobject/gbinding.c @@ -35,9 +35,9 @@ * G_BINDING_DEFAULT); * ]| * - * will cause object2:property-b to be updated every - * time g_object_set() or the specific accessor changes the value of - * object1:property-a. + * will cause the property named "property-b" of @object2 to be updated + * every time g_object_set() or the specific accessor changes the value of + * the property "property-a" of @object1. * * It is possible to create a bidirectional binding between two properties * of two #GObject instances, so that if either property changes, the @@ -65,15 +65,15 @@ * NULL, NULL); * ]| * - * will keep the value property of the two adjustments - * in sync; the celsius_to_fahrenheit function will be - * called whenever the adjustment1:value property changes - * and will transform the current value of the property before applying it - * to the adjustment2:value property; vice versa, the - * fahrenheit_to_celsius function will be called whenever - * the adjustment2:value property changes, and will - * transform the current value of the property before applying it to the - * adjustment1:value. + * will keep the "value" property of the two adjustments in sync; the + * @celsius_to_fahrenheit function will be called whenever the "value" + * property of @adjustment1 changes and will transform the current value + * of the property before applying it to the "value" property of @adjustment2. + * + * Vice versa, the @fahrenheit_to_celsius function will be called whenever + * the "value" property of @adjustment2 changes, and will transform the + * current value of the property before applying it to the "value" property + * of @adjustment1. * * Note that #GBinding does not resolve cycles by itself; a cycle like * diff --git a/gobject/gsignal.c b/gobject/gsignal.c index 317a8f1..d11206f 100644 --- a/gobject/gsignal.c +++ b/gobject/gsignal.c @@ -43,24 +43,26 @@ * and a general purpose notification mechanism * @title: Signals * - * The basic concept of the signal system is that of the - * emission of a signal. Signals are introduced - * per-type and are identified through strings. Signals introduced - * for a parent type are available in derived types as well, so - * basically they are a per-type facility that is inherited. A signal - * emission mainly involves invocation of a certain set of callbacks - * in precisely defined manner. There are two main categories of such - * callbacks, per-object ones and user provided ones. + * The basic concept of the signal system is that of the emission + * of a signal. Signals are introduced per-type and are identified + * through strings. Signals introduced for a parent type are available + * in derived types as well, so basically they are a per-type facility + * that is inherited. + * + * A signal emission mainly involves invocation of a certain set of + * 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 * referring to those types as "object types" in the following, simply * because that is the context most users will encounter signals in.) * The per-object callbacks are most often referred to as "object method * handler" or "default (signal) handler", while user provided callbacks are * usually just called "signal handler". + * * The object method handler is provided at signal creation time (this most * frequently happens at the end of an object class' creation), while user - * provided handlers are frequently connected and disconnected to/from a certain - * signal on certain object instances. + * provided handlers are frequently connected and disconnected to/from a + * certain signal on certain object instances. * * A signal emission consists of five stages, unless prematurely stopped: * @@ -68,13 +70,13 @@ * 1 - Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals * * - * 2 - Invocation of normal user-provided signal handlers (after flag %FALSE) + * 2 - Invocation of normal user-provided signal handlers (where the @after flag is not set) * * * 3 - Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals * * - * 4 - Invocation of user provided signal handlers, connected with an after flag of %TRUE + * 4 - Invocation of user provided signal handlers (where the @after flag is set) * * * 5 - Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals @@ -82,17 +84,20 @@ * * The user-provided signal handlers are called in the order they were * connected in. + * * All handlers may prematurely stop a signal emission, and any number of * handlers may be connected, disconnected, blocked or unblocked during * a signal emission. + * * There are certain criteria for skipping user handlers in stages 2 and 4 * of a signal emission. - * First, user handlers may be blocked, blocked handlers are omitted - * during callback invocation, to return from the "blocked" state, a - * handler has to get unblocked exactly the same amount of times - * it has been blocked before. + * + * First, user handlers may be blocked. Blocked handlers are omitted during + * callback invocation, to return from the blocked state, a handler has to + * get unblocked exactly the same amount of times it has been blocked before. + * * 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. * Specification of no detail argument for signal handlers (omission of the * 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 * callbacks will be invoked, while a return of %FALSE allows * the emission to continue. The idea here is that a %TRUE return - * indicates that the callback handled the signal, - * and no further handling is needed. + * indicates that the callback handled the signal, and no further + * handling is needed. * * Since: 2.4 * diff --git a/gobject/gtype.c b/gobject/gtype.c index 4608ebd..d729da6 100644 --- a/gobject/gtype.c +++ b/gobject/gtype.c @@ -50,15 +50,18 @@ * unloaded at run-time as dynamic types may be. Static types are created * with g_type_register_static() that gets type specific information passed * in via a #GTypeInfo structure. + * * Dynamic types are created with g_type_register_dynamic() which takes a * #GTypePlugin structure instead. The remaining type information (the * #GTypeInfo structure) is retrieved during runtime through #GTypePlugin * and the g_type_plugin_*() API. + * * These registration functions are usually called only once from a * function whose only purpose is to return the type identifier for a * specific class. Once the type (or class or interface) is registered, * it may be instantiated, inherited, or implemented depending on exactly * what sort of type it is. + * * There is also a third registration function for registering fundamental * types called g_type_register_fundamental() which requires both a #GTypeInfo * 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 * to the buffer in the structure. * - * A final word about type names. - * Such an identifier needs to be at least three characters long. There is no - * upper length limit. The first character needs to be a letter (a-z or A-Z) - * or an underscore '_'. Subsequent characters can be letters, numbers or - * any of '-_+'. + * A final word about type names: Such an identifier needs to be at least + * three characters long. There is no upper length limit. The first character + * needs to be a letter (a-z or A-Z) or an underscore '_'. Subsequent + * characters can be letters, numbers or any of '-_+'. */ @@ -396,15 +398,15 @@ lookup_type_node_I (register GType utype) /** * g_type_get_type_registration_serial: * - * Returns an opaque serial number that represents the state of the set of - * registered types. Any time a type is registered this serial changes, + * Returns an opaque serial number that represents the state of the set + * of registered types. Any time a type is registered this serial changes, * 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 * time by comparing the current serial with the one at the type lookup. * * Since: 2.36 * - * Returns: An unsigned int, representing the state of type registrations. + * Returns: An unsigned int, representing the state of type registrations */ guint g_type_get_type_registration_serial (void) @@ -1548,8 +1550,8 @@ type_iface_add_prerequisite_W (TypeNode *iface, /** * g_type_interface_add_prerequisite: - * @interface_type: #GType value of an interface type. - * @prerequisite_type: #GType value of an interface or instantiatable type. + * @interface_type: #GType value of an interface type + * @prerequisite_type: #GType value of an interface or instantiatable type * * Adds @prerequisite_type to the list of prerequisites of @interface_type. * This means that any type implementing @interface_type must also implement @@ -1636,15 +1638,15 @@ g_type_interface_add_prerequisite (GType interface_type, * g_type_interface_prerequisites: * @interface_type: an interface type * @n_prerequisites: (out) (allow-none): location to return the number - * of prerequisites, or %NULL + * of prerequisites, or %NULL * * Returns the prerequisites of an interfaces type. * * Since: 2.2 * * Returns: (array length=n_prerequisites) (transfer full): a - * newly-allocated zero-terminated array of #GType containing - * the prerequisites of @interface_type + * newly-allocated zero-terminated array of #GType containing + * the prerequisites of @interface_type */ GType* g_type_interface_prerequisites (GType interface_type, @@ -1766,7 +1768,7 @@ type_iface_blow_holder_info_Wm (TypeNode *iface, /** * 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 * 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 * implementation. So use of g_type_create_instance() is reserved for * implementators of fundamental types only. E.g. instances of the - * #GObject hierarchy should be created via g_object_new() and - * never directly through - * g_type_create_instance() which doesn't handle things like singleton - * objects or object construction. Note: Do not - * use this function, unless you're implementing a 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. + * #GObject hierarchy should be created via g_object_new() and never + * directly through g_type_create_instance() which doesn't handle things + * like singleton objects or object construction. + * + * Note: Do not use this function, unless you're implementing a + * 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* g_type_create_instance (GType type) @@ -1872,7 +1874,7 @@ g_type_create_instance (GType type) /** * 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 * 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) * @check_data: data to pass to @check_func * @check_func: function to be called after each interface - * is initialized. + * is initialized * * Adds a function to be called after an interface vtable is - * initialized for any class (i.e. after the @interface_init member of - * #GInterfaceInfo has been called). + * initialized for any class (i.e. after the @interface_init + * member of #GInterfaceInfo has been called). * - * This function is useful when you want to check an invariant that - * depends on the interfaces of a class. For instance, the + * This function is useful when you want to check an invariant + * that depends on the interfaces of a class. For instance, the * implementation of #GObject uses this facility to check that an * object implements all of the properties that are defined on its * interfaces. @@ -2584,21 +2586,21 @@ g_type_remove_interface_check (gpointer check_data, /* --- type registration --- */ /** * g_type_register_fundamental: - * @type_id: A predefined type identifier. - * @type_name: 0-terminated string used as the name of the new type. - * @info: The #GTypeInfo structure for this type. - * @finfo: The #GTypeFundamentalInfo structure for this type. - * @flags: Bitwise combination of #GTypeFlags values. + * @type_id: a predefined type identifier + * @type_name: 0-terminated string used as the name of the new type + * @info: #GTypeInfo structure for this type + * @finfo: #GTypeFundamentalInfo structure for this type + * @flags: bitwise combination of #GTypeFlags values * * 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 - * named @type_name is already registered, the behaviour is undefined. The type - * system uses the information contained in the #GTypeInfo structure pointed to - * by @info and the #GTypeFundamentalInfo structure pointed to by @finfo to - * manage the type and its instances. The value of @flags determines additional - * characteristics of the fundamental type. - * - * Returns: The predefined type identifier. + * name of a fundamental type. If @type_id is already registered, or a + * type named @type_name is already registered, the behaviour is undefined. + * The type system uses the information contained in the #GTypeInfo structure + * pointed to by @info and the #GTypeFundamentalInfo structure pointed to by + * @finfo to manage the type and its instances. The value of @flags determines + * additional characteristics of the fundamental type. + * + * Returns: the predefined type identifier */ GType g_type_register_fundamental (GType type_id, @@ -2654,13 +2656,13 @@ g_type_register_fundamental (GType type_id, /** * g_type_register_static_simple: (skip) - * @parent_type: Type from which this type will be derived. - * @type_name: 0-terminated string used as the name of the new type. - * @class_size: Size of the class structure (see #GTypeInfo) - * @class_init: Location of the class initialization function (see #GTypeInfo) - * @instance_size: Size of the instance structure (see #GTypeInfo) - * @instance_init: Location of the instance initialization function (see #GTypeInfo) - * @flags: Bitwise combination of #GTypeFlags values. + * @parent_type: type from which this type will be derived + * @type_name: 0-terminated string used as the name of the new type + * @class_size: size of the class structure (see #GTypeInfo) + * @class_init: location of the class initialization function (see #GTypeInfo) + * @instance_size: size of the instance structure (see #GTypeInfo) + * @instance_init: location of the instance initialization function (see #GTypeInfo) + * @flags: bitwise combination of #GTypeFlags values * * Registers @type_name as the name of a new static type derived from * @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 * - * Returns: The new type identifier. + * Returns: the new type identifier */ GType g_type_register_static_simple (GType parent_type, @@ -2704,18 +2706,18 @@ g_type_register_static_simple (GType parent_type, /** * g_type_register_static: - * @parent_type: Type from which this type will be derived. - * @type_name: 0-terminated string used as the name of the new type. - * @info: The #GTypeInfo structure for this type. - * @flags: Bitwise combination of #GTypeFlags values. + * @parent_type: type from which this type will be derived + * @type_name: 0-terminated string used as the name of the new type + * @info: #GTypeInfo structure for this type + * @flags: bitwise combination of #GTypeFlags values * * 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 * #GTypeInfo structure pointed to by @info to manage the type and its - * 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. * - * Returns: The new type identifier. + * Returns: the new type identifier */ GType g_type_register_static (GType parent_type, @@ -2759,10 +2761,10 @@ g_type_register_static (GType parent_type, /** * g_type_register_dynamic: - * @parent_type: Type from which this type will be derived. - * @type_name: 0-terminated string used as the name of the new type. - * @plugin: The #GTypePlugin structure to retrieve the #GTypeInfo from. - * @flags: Bitwise combination of #GTypeFlags values. + * @parent_type: type from which this type will be derived + * @type_name: 0-terminated string used as the name of the new type + * @plugin: #GTypePlugin structure to retrieve the #GTypeInfo from + * @flags: bitwise combination of #GTypeFlags values * * Registers @type_name as the name of a new dynamic type derived from * @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 * (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 g_type_register_dynamic (GType parent_type, @@ -2803,14 +2805,14 @@ g_type_register_dynamic (GType parent_type, /** * g_type_add_interface_static: - * @instance_type: #GType value of an instantiable type. - * @interface_type: #GType value of an interface type. - * @info: The #GInterfaceInfo structure for this - * (@instance_type, @interface_type) combination. - * - * Adds the static @interface_type to @instantiable_type. The - * information contained in the #GInterfaceInfo structure pointed to by - * @info is used to manage the relationship. + * @instance_type: #GType value of an instantiable type + * @interface_type: #GType value of an interface type + * @info: #GInterfaceInfo structure for this + * (@instance_type, @interface_type) combination + * + * Adds the static @interface_type to @instantiable_type. + * The information contained in the #GInterfaceInfo structure + * pointed to by @info is used to manage the relationship. */ void 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: - * @instance_type: the #GType value of an instantiable type. - * @interface_type: the #GType value of an interface type. - * @plugin: the #GTypePlugin structure to retrieve the #GInterfaceInfo from. + * @instance_type: #GType value of an instantiable type + * @interface_type: #GType value of an interface type + * @plugin: #GTypePlugin structure to retrieve the #GInterfaceInfo from * * Adds the dynamic @interface_type to @instantiable_type. The information * contained in the #GTypePlugin structure pointed to by @plugin @@ -2878,14 +2880,14 @@ g_type_add_interface_dynamic (GType instance_type, /* --- public API functions --- */ /** * 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 * @type. This function will demand-create the class if it doesn't * exist already. * - * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass - * structure for the given type ID. + * Returns: (type GObject.TypeClass) (transfer none): the #GTypeClass + * structure for the given type ID */ gpointer g_type_class_ref (GType type) @@ -2944,8 +2946,7 @@ g_type_class_ref (GType type) /** * g_type_class_unref: - * @g_class: (type GObject.TypeClass): The #GTypeClass structure to - * unreference. + * @g_class: (type GObject.TypeClass): a #GTypeClass structure to unref * * Decrements the reference count of the class structure being passed in. * 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_class: (type GObject.TypeClass): The #GTypeClass structure to - * unreference. + * @g_class: (type GObject.TypeClass): a #GTypeClass structure to unref * * A variant of g_type_class_unref() for use in #GTypeClassCacheFunc * implementations. It unreferences a class without consulting the chain - * of #GTypeClassCacheFuncs, avoiding the recursion which would occur + * of #GTypeClassCacheFuncs, avoiding the recursion which would occur * otherwise. */ void @@ -2996,16 +2996,17 @@ g_type_class_unref_uncached (gpointer g_class) /** * 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 - * the classes reference count isn't incremented. As a consequence, this function - * may return %NULL if the class of the type passed in does not currently - * exist (hasn't been referenced before). + * This function is essentially the same as g_type_class_ref(), + * except that the classes reference count isn't incremented. + * As a consequence, this function may return %NULL if the class + * of the type passed in does not currently exist (hasn't been + * referenced before). * - * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass - * structure for the given type ID or %NULL if the class does not - * currently exist. + * Returns: (type GObject.TypeClass) (transfer none): the #GTypeClass + * structure for the given type ID or %NULL if the class does not + * currently exist */ gpointer g_type_class_peek (GType type) @@ -3026,15 +3027,16 @@ g_type_class_peek (GType type) /** * 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 * static types. * + * Returns: (type GObject.TypeClass) (transfer none): the #GTypeClass + * structure for the given type ID or %NULL if the class does not + * currently exist or is dynamically loaded + * * Since: 2.4 - * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass - * structure for the given type ID or %NULL if the class does not - * currently exist or is dynamically loaded. */ gpointer g_type_class_peek_static (GType type) @@ -3056,8 +3058,8 @@ g_type_class_peek_static (GType type) /** * g_type_class_peek_parent: - * @g_class: (type GObject.TypeClass): The #GTypeClass structure to - * retrieve the parent class for. + * @g_class: (type GObject.TypeClass): the #GTypeClass structure to + * retrieve the parent class for * * This is a convenience function often needed in class initializers. * 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))); * * - * Returns: (type GObject.TypeClass) (transfer none): The parent class - * of @g_class. + * Returns: (type GObject.TypeClass) (transfer none): the parent class + * of @g_class */ gpointer g_type_class_peek_parent (gpointer g_class) @@ -3099,15 +3101,15 @@ g_type_class_peek_parent (gpointer g_class) /** * g_type_interface_peek: - * @instance_class: (type GObject.TypeClass): A #GTypeClass structure. - * @iface_type: An interface ID which this class conforms to. + * @instance_class: (type GObject.TypeClass): a #GTypeClass structure + * @iface_type: an interface ID which this class conforms to * * Returns the #GTypeInterface structure of an interface to which the * passed in class conforms. * - * Returns: (type GObject.TypeInterface) (transfer none): The GTypeInterface - * structure of iface_type if implemented by @instance_class, %NULL - * otherwise + * Returns: (type GObject.TypeInterface) (transfer none): the #GTypeInterface + * structure of @iface_type if implemented by @instance_class, %NULL + * otherwise */ gpointer g_type_interface_peek (gpointer instance_class, @@ -3132,17 +3134,17 @@ g_type_interface_peek (gpointer instance_class, /** * 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 * of the instance type to which @g_iface belongs. This is useful when * deriving the implementation of an interface from the parent type and * then possibly overriding some methods. * - * Returns: (transfer none) (type GObject.TypeInterface): The - * corresponding #GTypeInterface structure of the parent type of the - * instance type to which @g_iface belongs, or %NULL if the parent - * type doesn't conform to the interface. + * Returns: (transfer none) (type GObject.TypeInterface): the + * corresponding #GTypeInterface structure of the parent type of the + * instance type to which @g_iface belongs, or %NULL if the parent + * type doesn't conform to the interface */ gpointer g_type_interface_peek_parent (gpointer g_iface) @@ -3184,8 +3186,8 @@ g_type_interface_peek_parent (gpointer g_iface) * Since: 2.4 * * Returns: (type GObject.TypeInterface) (transfer none): the default - * vtable for the interface; call g_type_default_interface_unref() - * when you are done using the interface. + * vtable for the interface; call g_type_default_interface_unref() + * when you are done using the interface. */ gpointer g_type_default_interface_ref (GType g_type) @@ -3234,8 +3236,8 @@ g_type_default_interface_ref (GType g_type) * Since: 2.4 * * Returns: (type GObject.TypeInterface) (transfer none): the default - * vtable for the interface, or %NULL if the type is not currently in - * use. + * vtable for the interface, or %NULL if the type is not currently + * in use */ gpointer 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_iface: (type GObject.TypeInterface): the default vtable - * structure for a interface, as returned by - * g_type_default_interface_ref() + * structure for a interface, as returned by g_type_default_interface_ref() * * Decrements the reference count for the type corresponding to the * 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: - * @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 * 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 * 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 * g_type_name (GType type) @@ -3308,11 +3309,11 @@ g_type_name (GType type) /** * 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. * - * Returns: The type names quark or 0. + * Returns: the type names quark or 0 */ GQuark g_type_qname (GType type) @@ -3326,14 +3327,14 @@ g_type_qname (GType type) /** * 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 * has been registered under this name (this is the preferred method * to find out by name whether a specific type has been registered * yet). * - * Returns: Corresponding type ID or 0. + * Returns: corresponding type ID or 0 */ GType g_type_from_name (const gchar *name) @@ -3351,12 +3352,12 @@ g_type_from_name (const gchar *name) /** * 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. * - * Returns: The parent type. + * Returns: the parent type */ GType g_type_parent (GType type) @@ -3370,12 +3371,12 @@ g_type_parent (GType type) /** * g_type_depth: - * @type: A #GType value. + * @type: a #GType * * 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. * - * Returns: The depth of @type. + * Returns: the depth of @type */ guint g_type_depth (GType type) @@ -3389,18 +3390,18 @@ g_type_depth (GType type) /** * g_type_next_base: - * @leaf_type: Descendant of @root_type and the type to be returned. - * @root_type: Immediate parent of the returned type. + * @leaf_type: descendant of @root_type and the type to be returned + * @root_type: immediate parent of the returned type * * Given a @leaf_type and a @root_type which is contained in its * anchestry, return the type that @root_type is the immediate parent - * of. In other words, this function determines the type that is + * of. In other words, this function determines the type that is * derived directly from @root_type which is also a base class of * @leaf_type. Given a root type and a leaf type, this function can * be used to determine the types and order in which the leaf type is * 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 g_type_next_base (GType type, @@ -3487,14 +3488,15 @@ type_node_conforms_to_U (TypeNode *node, /** * g_type_is_a: - * @type: Type to check anchestry for. - * @is_a_type: Possible anchestor of @type or interface @type could conform to. + * @type: type to check anchestry for + * @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 - * 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. * - * Returns: %TRUE if @type is_a @is_a_type holds true. + * Returns: %TRUE if @type is a @is_a_type */ gboolean g_type_is_a (GType type, @@ -3512,15 +3514,15 @@ g_type_is_a (GType type, /** * g_type_children: - * @type: The parent type. - * @n_children: (out) (allow-none): Optional #guint pointer to contain - * the number of child types. + * @type: the parent type + * @n_children: (out) (allow-none): location to store the length of + * the returned array, or %NULL * - * Return a newly allocated and 0-terminated array of type IDs, listing the - * child types of @type. The return value has to be g_free()ed after use. + * Return a newly allocated and 0-terminated array of type IDs, listing + * the child types of @type. * * 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* g_type_children (GType type, @@ -3555,16 +3557,15 @@ g_type_children (GType type, /** * g_type_interfaces: - * @type: The type to list interface types for. - * @n_interfaces: (out) (allow-none): Optional #guint pointer to - * contain the number of interface types. + * @type: the type to list interface types for + * @n_interfaces: (out) (allow-none): location to store the length of + * the returned array, or %NULL * - * Return a newly allocated and 0-terminated array of type IDs, listing the - * interface types that @type conforms to. The return value has to be - * g_free()ed after use. + * Return a newly allocated and 0-terminated array of type IDs, listing + * the interface types that @type conforms to. * - * Returns: (array length=n_interfaces) (transfer full): Newly - * allocated and 0-terminated array of interface types. + * Returns: (array length=n_interfaces) (transfer full): Newly allocated + * and 0-terminated array of interface types, free with g_free() */ GType* g_type_interfaces (GType type, @@ -3771,9 +3772,9 @@ type_add_flags_W (TypeNode *node, /** * g_type_query: - * @type: the #GType value of a static, classed type. - * @query: (out caller-allocates): A user provided structure that is - * filled in with constant values upon success. + * @type: #GType of a static, classed type + * @query: (out caller-allocates): a user provided structure that is + * filled in with constant values upon success * * Queries the type system for information about a specific type. * 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: - * @type: The #GType to retrieve the plugin for. + * @type: #GType to retrieve the plugin for * - * Returns the #GTypePlugin structure for @type or - * %NULL if @type does not have a #GTypePlugin structure. + * Returns the #GTypePlugin structure for @type. * - * Returns: (transfer none): The corresponding plugin if @type is a - * dynamic type, %NULL otherwise. + * Returns: (transfer none): the corresponding plugin + * if @type is a dynamic type, %NULL otherwise */ GTypePlugin* g_type_get_plugin (GType type) @@ -3869,16 +3869,16 @@ g_type_get_plugin (GType type) /** * g_type_interface_get_plugin: - * @instance_type: the #GType value of an instantiatable type. - * @interface_type: the #GType value of an interface type. + * @instance_type: #GType of an instantiatable type + * @interface_type: #GType of an interface type * * Returns the #GTypePlugin structure for the dynamic interface - * @interface_type which has been added to @instance_type, or %NULL if - * @interface_type has not been added to @instance_type or does not - * have a #GTypePlugin structure. See g_type_add_interface_dynamic(). + * @interface_type which has been added to @instance_type, or %NULL + * if @interface_type has not been added to @instance_type or does + * not have a #GTypePlugin structure. See g_type_add_interface_dynamic(). * * Returns: (transfer none): the #GTypePlugin for the dynamic - * interface @interface_type of @instance_type. + * interface @interface_type of @instance_type */ GTypePlugin* 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 * fundamental type identifier. * - * Returns: The nextmost fundamental type ID to be registered, - * or 0 if the type system ran out of fundamental type IDs. + * Returns: the next available fundamental type ID to be registered, + * or 0 if the type system ran out of fundamental type IDs */ GType g_type_fundamental_next (void) @@ -3944,7 +3944,7 @@ g_type_fundamental_next (void) * @type_id: valid type ID * * Internal function, used to extract the fundamental type ID portion. - * use G_TYPE_FUNDAMENTAL() instead. + * Use G_TYPE_FUNDAMENTAL() instead. * * Returns: fundamental type ID */ @@ -4058,12 +4058,12 @@ g_type_check_class_cast (GTypeClass *type_class, /** * 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() - * macro. + * Private helper function to aid implementation of the + * G_TYPE_CHECK_INSTANCE() macro. * - * Returns: %TRUE if @instance is valid, %FALSE otherwise. + * Returns: %TRUE if @instance is valid, %FALSE otherwise */ gboolean g_type_check_instance (GTypeInstance *type_instance) @@ -4154,15 +4154,16 @@ g_type_check_value_holds (GValue *value, /** * g_type_value_table_peek: (skip) - * @type: A #GType value. + * @type: a #GType * * Returns the location of the #GTypeValueTable associated with @type. - * Note that this function should only be used from source code + * + * Note that this function should only be used from source code * that implements or has internal knowledge of the implementation of - * @type. + * @type. * - * Returns: Location of the #GTypeValueTable associated with @type or - * %NULL if there is no #GTypeValueTable associated with @type. + * Returns: location of the #GTypeValueTable associated with @type or + * %NULL if there is no #GTypeValueTable associated with @type */ GTypeValueTable* g_type_value_table_peek (GType type) @@ -4266,8 +4267,8 @@ _g_type_boxed_init (GType type, /* --- initialization --- */ /** * g_type_init_with_debug_flags: - * @debug_flags: Bitwise combination of #GTypeDebugFlags values for - * debugging purposes. + * @debug_flags: bitwise combination of #GTypeDebugFlags values for + * debugging purposes * * This function used to initialise the type system with debugging * 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_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. * @@ -4681,8 +4682,8 @@ g_type_class_get_instance_private_offset (gpointer g_class) /** * g_type_add_class_private: - * @class_type: GType of an classed type. - * @private_size: size of private structure. + * @class_type: GType of an classed type + * @private_size: size of private structure * * Registers a private class structure for a classed type; * when the class is allocated, the private structures for @@ -4777,7 +4778,7 @@ g_type_class_get_private (GTypeClass *klass, /** * g_type_ensure: - * @type: a #GType. + * @type: a #GType * * Ensures that the indicated @type has been registered with the * type system, and its _class_init() method has been run. -- 2.7.4