From 64eface479baf3db06f0f42b43f391db55b5ad4d Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Fri, 31 Jan 2014 17:38:27 -0500 Subject: [PATCH] Docs: don't use the warning tag More markup removal --- gio/gdbusinterface.c | 11 +++++------ gio/gfile.c | 8 ++++---- gio/goutputstream.c | 10 +++++----- glib/docs.c | 9 ++++----- glib/genviron.c | 36 ++++++++++++++++-------------------- glib/grand.c | 10 +++++----- glib/gstrfuncs.c | 11 +++++------ glib/gvariant.c | 4 ++-- 8 files changed, 46 insertions(+), 53 deletions(-) diff --git a/gio/gdbusinterface.c b/gio/gdbusinterface.c index f6872d909..5c1b3552c 100644 --- a/gio/gdbusinterface.c +++ b/gio/gdbusinterface.c @@ -65,17 +65,16 @@ g_dbus_interface_get_info (GDBusInterface *interface_) /** * g_dbus_interface_get_object: (skip) - * @interface_: An exported D-Bus interface. + * @interface_: An exported D-Bus interface * * Gets the #GDBusObject that @interface_ belongs to, if any. * - * It is not safe to use the returned object if @interface_ - * or the returned object is being used from other threads. See - * g_dbus_interface_dup_object() for a thread-safe - * alternative. + * It is not safe to use the returned object if @interface_ or + * the returned object is being used from other threads. See + * g_dbus_interface_dup_object() for a thread-safe alternative. * * Returns: (transfer none): A #GDBusObject or %NULL. The returned - * reference belongs to @interface_ and should not be freed. + * reference belongs to @interface_ and should not be freed. * * Since: 2.30 */ diff --git a/gio/gfile.c b/gio/gfile.c index 4f54a66af..d438d1f77 100644 --- a/gio/gfile.c +++ b/gio/gfile.c @@ -7319,10 +7319,10 @@ replace_contents_open_callback (GObject *obj, * If @make_backup is %TRUE, this function will attempt to * make a backup of @file. * - * No copy of @content will be made, so it must stay valid until - * @callback is called. See g_file_replace_contents_bytes_async() for a #GBytes - * version that will automatically hold a reference to the contents (without - * copying) for the duration of the call. + * Note that no copy of @content will be made, so it must stay valid + * until @callback is called. See g_file_replace_contents_bytes_async() + * for a #GBytes version that will automatically hold a reference to the + * contents (without copying) for the duration of the call. */ void g_file_replace_contents_async (GFile *file, diff --git a/gio/goutputstream.c b/gio/goutputstream.c index 125c41819..a94f4c254 100644 --- a/gio/goutputstream.c +++ b/gio/goutputstream.c @@ -786,11 +786,11 @@ async_ready_write_callback_wrapper (GObject *source_object, * For the synchronous, blocking version of this function, see * g_output_stream_write(). * - * No copy of @buffer will be made, so it must stay valid until - * @callback is called. See g_output_stream_write_bytes_async() for a #GBytes - * version that will automatically hold a reference to the contents (without - * copying) for the duration of the call. - **/ + * Note that no copy of @buffer will be made, so it must stay valid + * until @callback is called. See g_output_stream_write_bytes_async() + * for a #GBytes version that will automatically hold a reference to + * the contents (without copying) for the duration of the call. + */ void g_output_stream_write_async (GOutputStream *stream, const void *buffer, diff --git a/glib/docs.c b/glib/docs.c index 2b14de15c..c73dfc2be 100644 --- a/glib/docs.c +++ b/glib/docs.c @@ -748,11 +748,10 @@ * The GLib macros GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. take care * to do the right thing on the every platform. * - * 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. - * + * Warning: 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. */ /** diff --git a/glib/genviron.c b/glib/genviron.c index d60371bde..44efd27e5 100644 --- a/glib/genviron.c +++ b/glib/genviron.c @@ -256,20 +256,18 @@ g_getenv (const gchar *variable) * Note that on some systems, when variables are overwritten, the memory * used for the previous variables and its value isn't reclaimed. * - * - * Environment variable handling in UNIX is not thread-safe, and your - * program may crash if one thread calls g_setenv() while another - * thread is calling getenv(). (And note that many functions, such as - * gettext(), call getenv() internally.) This function is only safe to - * use at the very start of your program, before creating any other - * threads (or creating objects that create worker threads of their - * own). - * + * You should be mindful fo the fact that environment variable handling + * in UNIX is not thread-safe, and your program may crash if one thread + * calls g_setenv() while another thread is calling getenv(). (And note + * that many functions, such as gettext(), call getenv() internally.) + * This function is only safe to use at the very start of your program, + * before creating any other threads (or creating objects that create + * worker threads of their own). + * * If you need to set up the environment for a child process, you can * use g_get_environ() to get an environment array, modify that with * g_environ_setenv() and g_environ_unsetenv(), and then pass that * array directly to execvpe(), g_spawn_async(), or the like. - * * * Returns: %FALSE if the environment variable couldn't be set. * @@ -323,20 +321,18 @@ extern char **environ; * Note that on some systems, when variables are overwritten, the * memory used for the previous variables and its value isn't reclaimed. * - * - * Environment variable handling in UNIX is not thread-safe, and your - * program may crash if one thread calls g_unsetenv() while another - * thread is calling getenv(). (And note that many functions, such as - * gettext(), call getenv() internally.) This function is only safe - * to use at the very start of your program, before creating any other - * threads (or creating objects that create worker threads of their - * own). - * + * You should be mindful of the fact that environment variable handling + * in UNIX is not thread-safe, and your program may crash if one thread + * calls g_unsetenv() while another thread is calling getenv(). (And note + * that many functions, such as gettext(), call getenv() internally.) This + * function is only safe to use at the very start of your program, before + * creating any other threads (or creating objects that create worker + * threads of their own). + * * If you need to set up the environment for a child process, you can * use g_get_environ() to get an environment array, modify that with * g_environ_setenv() and g_environ_unsetenv(), and then pass that * array directly to execvpe(), g_spawn_async(), or the like. - * * * Since: 2.4 */ diff --git a/glib/grand.c b/glib/grand.c index fd657b654..1ade68d30 100644 --- a/glib/grand.c +++ b/glib/grand.c @@ -66,8 +66,8 @@ * The following functions allow you to use a portable, fast and good * pseudo-random number generator (PRNG). * - * Do not use this API for cryptographic purposes such as key - * generation, nonces, salts or one-time pads. + * Do not use this API for cryptographic purposes such as key + * generation, nonces, salts or one-time pads. * * This PRNG is suitable for non-cryptographic use such as in games * (shuffling a card deck, generating levels), generating data for a @@ -358,11 +358,11 @@ g_rand_set_seed (GRand* rand, guint32 seed) * @seed: array to initialize with * @seed_length: length of array * - * Initializes the random number generator by an array of - * longs. Array can be of arbitrary size, though only the + * Initializes the random number generator by an array of longs. + * Array can be of arbitrary size, though only the * first 624 values are taken. This function is useful * if you have many low entropy seeds, or if you require more then - * 32bits of actual entropy for your application. + * 32 bits of actual entropy for your application. * * Since: 2.4 **/ diff --git a/glib/gstrfuncs.c b/glib/gstrfuncs.c index 89d212db4..4cfcf24a7 100644 --- a/glib/gstrfuncs.c +++ b/glib/gstrfuncs.c @@ -543,17 +543,16 @@ g_strdup_printf (const gchar *format, * @string1: the first string to add, which must not be %NULL * @...: a %NULL-terminated list of strings to append to the string * - * Concatenates all of the given strings into one long string. - * The returned string should be freed with g_free() when no longer needed. + * Concatenates all of the given strings into one long string. The + * returned string should be freed with g_free() when no longer needed. + * + * The variable argument list must end with %NULL. If you forget the %NULL, + * g_strconcat() will start appending random memory junk to your string. * * Note that this function is usually not the right function to use to * assemble a translated message from pieces, since proper translation * often requires the pieces to be reordered. * - * The variable argument list must end - * with %NULL. If you forget the %NULL, g_strconcat() will start appending - * random memory junk to your string. - * * Returns: a newly-allocated string containing all the string arguments */ gchar* diff --git a/glib/gvariant.c b/glib/gvariant.c index 6c9a9c658..591dcf396 100644 --- a/glib/gvariant.c +++ b/glib/gvariant.c @@ -199,7 +199,7 @@ * * Array type info structures are 6 * sizeof (void *), plus the * memory required to store the type string itself. This means that - * on 32bit systems, the cache entry for "a{sv}" would require 30 + * on 32-bit systems, the cache entry for "a{sv}" would require 30 * bytes of memory (plus malloc overhead). * * @@ -208,7 +208,7 @@ * required to store the type string itself. A 2-item tuple, for * example, would have a type information structure that consumed * writable memory in the size of 14 * sizeof (void *) (plus type - * string) This means that on 32bit systems, the cache entry for + * string) This means that on 32-bit systems, the cache entry for * "{sv}" would require 61 bytes of memory (plus malloc overhead). * *