From b8b3c7e25702bbd04cd4b5a27648784e445f5014 Mon Sep 17 00:00:00 2001 From: Rico Tzschichholz Date: Mon, 19 Aug 2013 22:38:19 +0200 Subject: Update annotations from glib git --- gir/gio-2.0.c | 32 ++++++----- gir/glib-2.0.c | 167 ++++++++++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 162 insertions(+), 37 deletions(-) diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index 064e968c..80fe1cb7 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -2393,7 +2393,7 @@ /** * GSocket:broadcast: * - * Whether the socket should allow sending to and receiving from broadcast addresses. + * Whether the socket should allow sending to broadcast addresses. * * Since: 2.32 */ @@ -29685,14 +29685,20 @@ * In certain situations, you may also want to bind a socket that will be * used to initiate connections, though this is not normally required. * - * @allow_reuse should be %TRUE for server sockets (sockets that you will - * eventually call g_socket_accept() on), and %FALSE for client sockets. - * (Specifically, if it is %TRUE, then g_socket_bind() will set the - * %SO_REUSEADDR flag on the socket, allowing it to bind @address even if - * that address was previously used by another socket that has not yet been - * fully cleaned-up by the kernel. Failing to set this flag on a server - * socket may cause the bind call to return %G_IO_ERROR_ADDRESS_IN_USE if - * the server program is stopped and then immediately restarted.) + * If @socket is a TCP socket, then @allow_reuse controls the setting + * of the SO_REUSEADDR socket option; normally it + * should be %TRUE for server sockets (sockets that you will + * eventually call g_socket_accept() on), and %FALSE for client + * sockets. (Failing to set this flag on a server socket may cause + * g_socket_bind() to return %G_IO_ERROR_ADDRESS_IN_USE if the server + * program is stopped and then immediately restarted.) + * + * If @socket is a UDP socket, then @allow_reuse determines whether or + * not other UDP sockets can be bound to the same address at the same + * time. In particular, you can have several UDP sockets bound to the + * same address, and they will all receive all of the multicast and + * broadcast packets sent to that address. (The behavior of unicast + * UDP packets to an address with multiple listeners is not defined.) * * Returns: %TRUE on success, %FALSE on error. * Since: 2.22 @@ -30729,7 +30735,7 @@ * * Gets the broadcast setting on @socket; if %TRUE, * it is possible to send packets to broadcast - * addresses or receive from broadcast addresses. + * addresses. * * Returns: the broadcast setting on @socket * Since: 2.32 @@ -31662,10 +31668,10 @@ /** * g_socket_set_broadcast: * @socket: a #GSocket. - * @broadcast: whether @socket should allow sending to and receiving from broadcast addresses + * @broadcast: whether @socket should allow sending to broadcast addresses * - * Sets whether @socket should allow sending to and receiving from - * broadcast addresses. This is %FALSE by default. + * Sets whether @socket should allow sending to broadcast addresses. + * This is %FALSE by default. * * Since: 2.32 */ diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index e5b73062..a01b5d27 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -8721,11 +8721,10 @@ * @cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. * @n2: another floating point number * - * Debugging macro to terminate the application with a warning - * message if a floating point number comparison fails. + * Debugging macro to compare two floating point numbers. * * The effect of g_assert_cmpfloat (n1, op, n2) is - * the same as g_assert (n1 op n2). The advantage + * the same as g_assert_true (n1 op n2). The advantage * of this macro is that it can produce a message that includes the * actual values of @n1 and @n2. * @@ -8739,8 +8738,7 @@ * @cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. * @n2: another unsigned integer * - * Debugging macro to terminate the application with a warning - * message if an unsigned integer comparison fails. + * Debugging macro to compare to unsigned integers. * * This is a variant of g_assert_cmpuint() that displays the numbers * in hexadecimal notation in the message. @@ -8755,11 +8753,10 @@ * @cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. * @n2: another integer * - * Debugging macro to terminate the application with a warning - * message if an integer comparison fails. + * Debugging macro to compare two integers. * * The effect of g_assert_cmpint (n1, op, n2) is - * the same as g_assert (n1 op n2). The advantage + * the same as g_assert_true (n1 op n2). The advantage * of this macro is that it can produce a message that includes the * actual values of @n1 and @n2. * @@ -8773,12 +8770,13 @@ * @cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. * @s2: another string (may be %NULL) * - * Debugging macro to terminate the application with a warning - * message if a string comparison fails. The strings are compared - * using g_strcmp0(). + * Debugging macro to compare two strings. If the comparison fails, + * an error message is logged and the application is either terminated + * or the testcase marked as failed. + * The strings are compared using g_strcmp0(). * * The effect of g_assert_cmpstr (s1, op, s2) is - * the same as g_assert (g_strcmp0 (s1, s2) op 0). + * the same as g_assert_true (g_strcmp0 (s1, s2) op 0). * The advantage of this macro is that it can produce a message that * includes the actual values of @s1 and @s2. * @@ -8796,11 +8794,10 @@ * @cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. * @n2: another unsigned integer * - * Debugging macro to terminate the application with a warning - * message if an unsigned integer comparison fails. + * Debugging macro to compare two unsigned integers. * * The effect of g_assert_cmpuint (n1, op, n2) is - * the same as g_assert (n1 op n2). The advantage + * the same as g_assert_true (n1 op n2). The advantage * of this macro is that it can produce a message that includes the * actual values of @n1 and @n2. * @@ -8814,11 +8811,11 @@ * @dom: the expected error domain (a #GQuark) * @c: the expected error code * - * Debugging macro to terminate the application with a warning - * message if a method has not returned the correct #GError. + * Debugging macro to check that a method has returned + * the correct #GError. * * The effect of g_assert_error (err, dom, c) is - * the same as g_assert (err != NULL && err->domain + * the same as g_assert_true (err != NULL && err->domain * == dom && err->code == c). The advantage of this * macro is that it can produce a message that includes the incorrect * error message and code. @@ -8831,15 +8828,30 @@ */ +/** + * g_assert_false: + * @expr: the expression to check + * + * Debugging macro to check an expression is false. + * + * If the assertion fails (i.e. the expression is not false), + * an error message is logged and the application is either + * terminated or the testcase marked as failed. + * + * See g_test_set_nonfatal_assertions(). + * + * Since: 2.38 + */ + + /** * g_assert_no_error: * @err: a #GError, possibly %NULL * - * Debugging macro to terminate the application with a warning - * message if a method has returned a #GError. + * Debugging macro to check that a #GError is not set. * * The effect of g_assert_no_error (err) is - * the same as g_assert (err == NULL). The advantage + * the same as g_assert_true (err == NULL). The advantage * of this macro is that it can produce a message that includes * the error message and code. * @@ -8859,6 +8871,38 @@ */ +/** + * g_assert_null: + * @expr: the expression to check + * + * Debugging macro to check an expression is %NULL. + * + * If the assertion fails (i.e. the expression is not %NULL), + * an error message is logged and the application is either + * terminated or the testcase marked as failed. + * + * See g_test_set_nonfatal_assertions(). + * + * Since: 2.38 + */ + + +/** + * g_assert_true: + * @expr: the expression to check + * + * Debugging macro to check that an expression is true. + * + * If the assertion fails (i.e. the expression is not true), + * an error message is logged and the application is either + * terminated or the testcase marked as failed. + * + * See g_test_set_nonfatal_assertions(). + * + * Since: 2.38 + */ + + /** * g_async_queue_length: * @queue: a #GAsyncQueue. @@ -16369,7 +16413,7 @@ /** * g_io_channel_read_unichar: * @channel: a #GIOChannel - * @thechar: a location to return a character + * @thechar: (out): a location to return a character * @error: a location to return an error of type #GConvertError or #GIOChannelError * * Reads a Unicode character from @channel. @@ -27499,6 +27543,25 @@ */ +/** + * g_test_failed: + * + * Returns whether a test has already failed. This will + * be the case when g_test_fail(), g_test_incomplete() + * or g_test_skip() have been called, but also if an + * assertion has failed. + * + * This can be useful to return early from a test if + * continuing after a failed assertion might be harmful. + * + * The return value of this function is only meaningful + * if it is called from inside a test function. + * + * Returns: %TRUE if the test has failed + * Since: 2.38 + */ + + /** * g_test_get_dir: * @file_type: the type of file (built vs. distributed) @@ -27548,6 +27611,25 @@ */ +/** + * g_test_incomplete: + * @msg: (allow-none): explanation + * + * Indicates that a test failed because of some incomplete + * functionality. This function can be called multiple times + * from the same test. + * + * Calling this function will not stop the test from running, you + * need to return from the test function yourself. So you can + * produce additional diagnostic messages or even continue running + * the test. + * + * If not called from inside a test, this function does nothing. + * + * Since: 2.38 + */ + + /** * g_test_init: * @argc: Address of the @argc parameter of the main() function. Changed if any arguments were handled. @@ -27918,6 +28000,42 @@ */ +/** + * g_test_set_nonfatal_assertions: + * + * Changes the behaviour of g_assert_cmpstr(), g_assert_cmpint(), + * g_assert_cmpuint(), g_assert_cmphex(), g_assert_cmpfloat(), + * g_assert_true(), g_assert_false(), g_assert_null(), g_assert_no_error(), + * g_assert_error(), g_test_assert_expected_messages() and the various + * g_test_trap_assert_*() macros to not abort to program, but instead + * call g_test_fail() and continue. + * + * Note that the g_assert_not_reached() and g_assert() are not + * affected by this. + * + * This function can only be called after g_test_init(). + * + * Since: 2.38 + */ + + +/** + * g_test_skip: + * @msg: (allow-none): explanation + * + * Indicates that a test was skipped. + * + * Calling this function will not stop the test from running, you + * need to return from the test function yourself. So you can + * produce additional diagnostic messages or even continue running + * the test. + * + * If not called from inside a test, this function does nothing. + * + * Since: 2.38 + */ + + /** * g_test_slow: * @@ -28281,7 +28399,7 @@ /** * g_thread_new: - * @name: a name for the new thread + * @name: (allow-none): an (optional) name for the new thread * @func: a function to execute in the new thread * @data: an argument to supply to the new thread * @@ -28292,6 +28410,7 @@ * with g_thread_join(). * * The @name can be useful for discriminating threads in a debugger. + * It is not used for other purposes and does not have to be unique. * Some systems restrict the length of @name to 16 bytes. * * If the thread can not be created the program aborts. See @@ -28584,7 +28703,7 @@ /** * g_thread_try_new: - * @name: a name for the new thread + * @name: (allow-none): an (optional) name for the new thread * @func: a function to execute in the new thread * @data: an argument to supply to the new thread * @error: return location for error, or %NULL -- cgit v1.2.1