From 3fa33317b7e9866793ce1ea32d069e8c9270caa2 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Wed, 12 Dec 2001 20:32:07 +0000 Subject: [PATCH] Documentation fixes. * glib/gconvert.c, glib/grand.c, glib/ghash.c, glib/gthreadpool.c, glib/gtree.c: Documentation fixes. * glib/tmpl/allocators.sgml, glib/tmpl/arrays.sgml, glib/tmpl/arrays_byte.sgml, glib/tmpl/arrays_pointer.sgml, glib/tmpl/caches.sgml, glib/tmpl/completion.sgml, glib/tmpl/conversions.sgml, glib/tmpl/datalist.sgml, glib/tmpl/date.sgml, glib/tmpl/error_reporting.sgml, glib/tmpl/fileutils.sgml, glib/tmpl/hash_tables.sgml, glib/tmpl/hooks.sgml, glib/tmpl/macros.sgml, glib/tmpl/macros_misc.sgml, glib/tmpl/main.sgml, glib/tmpl/markup.sgml, glib/tmpl/memory.sgml, glib/tmpl/memory_chunks.sgml, glib/tmpl/messages.sgml, glib/tmpl/misc_utils.sgml, glib/tmpl/modules.sgml, glib/tmpl/numerical.sgml, glib/tmpl/patterns.sgml, glib/tmpl/queue.sgml, glib/tmpl/shell.sgml, glib/tmpl/spawn.sgml, glib/tmpl/string_utils.sgml, glib/tmpl/thread_pools.sgml, glib/tmpl/threads.sgml, glib/tmpl/timers.sgml, glib/tmpl/trees-binary.sgml, glib/tmpl/trees-nary.sgml, glib/tmpl/type_conversion.sgml, glib/tmpl/unicode.sgml, glib/tmpl/warnings.sgml, glib/tmpl/windows.sgml: Improve markup of examples, general consistency improvements. --- ChangeLog | 5 + ChangeLog.pre-2-0 | 5 + ChangeLog.pre-2-10 | 5 + ChangeLog.pre-2-12 | 5 + ChangeLog.pre-2-2 | 5 + ChangeLog.pre-2-4 | 5 + ChangeLog.pre-2-6 | 5 + ChangeLog.pre-2-8 | 5 + docs/reference/ChangeLog | 23 +++ docs/reference/glib/tmpl/allocators.sgml | 2 +- docs/reference/glib/tmpl/arrays.sgml | 4 +- docs/reference/glib/tmpl/arrays_byte.sgml | 14 +- docs/reference/glib/tmpl/arrays_pointer.sgml | 12 +- docs/reference/glib/tmpl/caches.sgml | 8 +- docs/reference/glib/tmpl/completion.sgml | 17 +-- docs/reference/glib/tmpl/conversions.sgml | 2 +- docs/reference/glib/tmpl/datalist.sgml | 2 +- docs/reference/glib/tmpl/date.sgml | 10 +- docs/reference/glib/tmpl/error_reporting.sgml | 43 +++--- docs/reference/glib/tmpl/fileutils.sgml | 4 +- docs/reference/glib/tmpl/hash_tables.sgml | 6 +- docs/reference/glib/tmpl/hooks.sgml | 126 ++++------------ docs/reference/glib/tmpl/macros.sgml | 4 +- docs/reference/glib/tmpl/macros_misc.sgml | 35 ++--- docs/reference/glib/tmpl/main.sgml | 8 +- docs/reference/glib/tmpl/markup.sgml | 5 +- docs/reference/glib/tmpl/memory.sgml | 19 ++- docs/reference/glib/tmpl/memory_chunks.sgml | 2 +- docs/reference/glib/tmpl/messages.sgml | 19 ++- docs/reference/glib/tmpl/misc_utils.sgml | 11 +- docs/reference/glib/tmpl/modules.sgml | 2 +- docs/reference/glib/tmpl/numerical.sgml | 9 +- docs/reference/glib/tmpl/patterns.sgml | 3 +- docs/reference/glib/tmpl/queue.sgml | 2 +- docs/reference/glib/tmpl/shell.sgml | 2 +- docs/reference/glib/tmpl/spawn.sgml | 2 +- docs/reference/glib/tmpl/string_utils.sgml | 134 +++++++++--------- docs/reference/glib/tmpl/thread_pools.sgml | 2 +- docs/reference/glib/tmpl/threads.sgml | 35 +++-- docs/reference/glib/tmpl/timers.sgml | 2 +- docs/reference/glib/tmpl/trees-binary.sgml | 6 +- docs/reference/glib/tmpl/trees-nary.sgml | 10 +- docs/reference/glib/tmpl/type_conversion.sgml | 14 +- docs/reference/glib/tmpl/unicode.sgml | 6 +- docs/reference/glib/tmpl/warnings.sgml | 8 +- docs/reference/glib/tmpl/windows.sgml | 14 +- glib/gconvert.c | 60 ++++---- glib/ghash.c | 6 +- glib/grand.c | 22 +-- glib/gthreadpool.c | 24 ++-- glib/gtree.c | 14 +- 51 files changed, 381 insertions(+), 412 deletions(-) diff --git a/ChangeLog b/ChangeLog index 5dd5c16bd..ddf8a47f3 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2001-12-12 Matthias Clasen + + * glib/gconvert.c, glib/grand.c, glib/ghash.c, + glib/gthreadpool.c, glib/gtree.c: Documentation fixes. + Mon Dec 10 14:08:39 2001 HideToshi Tajima * glib/libcharset/config.charset (os): diff --git a/ChangeLog.pre-2-0 b/ChangeLog.pre-2-0 index 5dd5c16bd..ddf8a47f3 100644 --- a/ChangeLog.pre-2-0 +++ b/ChangeLog.pre-2-0 @@ -1,3 +1,8 @@ +2001-12-12 Matthias Clasen + + * glib/gconvert.c, glib/grand.c, glib/ghash.c, + glib/gthreadpool.c, glib/gtree.c: Documentation fixes. + Mon Dec 10 14:08:39 2001 HideToshi Tajima * glib/libcharset/config.charset (os): diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10 index 5dd5c16bd..ddf8a47f3 100644 --- a/ChangeLog.pre-2-10 +++ b/ChangeLog.pre-2-10 @@ -1,3 +1,8 @@ +2001-12-12 Matthias Clasen + + * glib/gconvert.c, glib/grand.c, glib/ghash.c, + glib/gthreadpool.c, glib/gtree.c: Documentation fixes. + Mon Dec 10 14:08:39 2001 HideToshi Tajima * glib/libcharset/config.charset (os): diff --git a/ChangeLog.pre-2-12 b/ChangeLog.pre-2-12 index 5dd5c16bd..ddf8a47f3 100644 --- a/ChangeLog.pre-2-12 +++ b/ChangeLog.pre-2-12 @@ -1,3 +1,8 @@ +2001-12-12 Matthias Clasen + + * glib/gconvert.c, glib/grand.c, glib/ghash.c, + glib/gthreadpool.c, glib/gtree.c: Documentation fixes. + Mon Dec 10 14:08:39 2001 HideToshi Tajima * glib/libcharset/config.charset (os): diff --git a/ChangeLog.pre-2-2 b/ChangeLog.pre-2-2 index 5dd5c16bd..ddf8a47f3 100644 --- a/ChangeLog.pre-2-2 +++ b/ChangeLog.pre-2-2 @@ -1,3 +1,8 @@ +2001-12-12 Matthias Clasen + + * glib/gconvert.c, glib/grand.c, glib/ghash.c, + glib/gthreadpool.c, glib/gtree.c: Documentation fixes. + Mon Dec 10 14:08:39 2001 HideToshi Tajima * glib/libcharset/config.charset (os): diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4 index 5dd5c16bd..ddf8a47f3 100644 --- a/ChangeLog.pre-2-4 +++ b/ChangeLog.pre-2-4 @@ -1,3 +1,8 @@ +2001-12-12 Matthias Clasen + + * glib/gconvert.c, glib/grand.c, glib/ghash.c, + glib/gthreadpool.c, glib/gtree.c: Documentation fixes. + Mon Dec 10 14:08:39 2001 HideToshi Tajima * glib/libcharset/config.charset (os): diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6 index 5dd5c16bd..ddf8a47f3 100644 --- a/ChangeLog.pre-2-6 +++ b/ChangeLog.pre-2-6 @@ -1,3 +1,8 @@ +2001-12-12 Matthias Clasen + + * glib/gconvert.c, glib/grand.c, glib/ghash.c, + glib/gthreadpool.c, glib/gtree.c: Documentation fixes. + Mon Dec 10 14:08:39 2001 HideToshi Tajima * glib/libcharset/config.charset (os): diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8 index 5dd5c16bd..ddf8a47f3 100644 --- a/ChangeLog.pre-2-8 +++ b/ChangeLog.pre-2-8 @@ -1,3 +1,8 @@ +2001-12-12 Matthias Clasen + + * glib/gconvert.c, glib/grand.c, glib/ghash.c, + glib/gthreadpool.c, glib/gtree.c: Documentation fixes. + Mon Dec 10 14:08:39 2001 HideToshi Tajima * glib/libcharset/config.charset (os): diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 82a955dc6..cc38554b4 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,26 @@ +2001-12-12 Matthias Clasen + + * glib/tmpl/allocators.sgml, glib/tmpl/arrays.sgml, + glib/tmpl/arrays_byte.sgml, glib/tmpl/arrays_pointer.sgml, + glib/tmpl/caches.sgml, glib/tmpl/completion.sgml, + glib/tmpl/conversions.sgml, + glib/tmpl/datalist.sgml, glib/tmpl/date.sgml, + glib/tmpl/error_reporting.sgml, glib/tmpl/fileutils.sgml, + glib/tmpl/hash_tables.sgml, + glib/tmpl/hooks.sgml, glib/tmpl/macros.sgml, + glib/tmpl/macros_misc.sgml, glib/tmpl/main.sgml, glib/tmpl/markup.sgml, + glib/tmpl/memory.sgml, glib/tmpl/memory_chunks.sgml, + glib/tmpl/messages.sgml, glib/tmpl/misc_utils.sgml, + glib/tmpl/modules.sgml, glib/tmpl/numerical.sgml, + glib/tmpl/patterns.sgml, glib/tmpl/queue.sgml, + glib/tmpl/shell.sgml, glib/tmpl/spawn.sgml, + glib/tmpl/string_utils.sgml, glib/tmpl/thread_pools.sgml, + glib/tmpl/threads.sgml, glib/tmpl/timers.sgml, + glib/tmpl/trees-binary.sgml, glib/tmpl/trees-nary.sgml, + glib/tmpl/type_conversion.sgml, glib/tmpl/unicode.sgml, + glib/tmpl/warnings.sgml, glib/tmpl/windows.sgml: + Improve markup of examples, general consistency improvements. + 2001-12-06 Havoc Pennington * glib/tmpl/messages.sgml: improve g_log_set_handler docs diff --git a/docs/reference/glib/tmpl/allocators.sgml b/docs/reference/glib/tmpl/allocators.sgml index 6b12fd27c..a98496c81 100644 --- a/docs/reference/glib/tmpl/allocators.sgml +++ b/docs/reference/glib/tmpl/allocators.sgml @@ -36,7 +36,7 @@ elements. Each must use separate allocators. -The #GAllocator struct contains private data. and should only be accessed +The GAllocator struct contains private data. and should only be accessed using the following functions. diff --git a/docs/reference/glib/tmpl/arrays.sgml b/docs/reference/glib/tmpl/arrays.sgml index 0de6c9091..c5c5e2a70 100644 --- a/docs/reference/glib/tmpl/arrays.sgml +++ b/docs/reference/glib/tmpl/arrays.sgml @@ -31,7 +31,7 @@ To set the size of an array, use g_array_set_size(). To free an array, use g_array_free(). -Using a GArray to store gint values. +Using a <structname>GArray</structname> to store gint values. GArray *garray; gint i; @@ -240,7 +240,7 @@ Returns the element of a #GArray at the given index. The return value is cast to the given type. -Getting a pointer to an element in a GArray. +Getting a pointer to an element in a <structname>GArray</structname>. EDayViewEvent *event; diff --git a/docs/reference/glib/tmpl/arrays_byte.sgml b/docs/reference/glib/tmpl/arrays_byte.sgml index 447f1360f..e59af2dd1 100644 --- a/docs/reference/glib/tmpl/arrays_byte.sgml +++ b/docs/reference/glib/tmpl/arrays_byte.sgml @@ -6,7 +6,7 @@ arrays of bytes, which grow automatically as elements are added. -GByteArray is based on #GArray, to provide arrays of bytes which grow +#GByteArray is based on #GArray, to provide arrays of bytes which grow automatically as elements are added. @@ -17,19 +17,19 @@ To add elements to a #GByteArray, use g_byte_array_append(), and g_byte_array_prepend(). -To set the size of a GByteArray, use g_byte_array_set_size(). +To set the size of a #GByteArray, use g_byte_array_set_size(). -To free a GByteArray, use g_byte_array_free(). +To free a #GByteArray, use g_byte_array_free(). -Using a GByteArray. +Using a <structname>GByteArray</structname>. GByteArray *gbarray; gint i; - gbarray = g_byte_array_new (); + gbarray = g_byte_array_new (); for (i = 0; i < 10000; i++) g_byte_array_append (gbarray, (guint8*) "abcd", 4); @@ -51,7 +51,7 @@ To free a GByteArray, use g_byte_array_free(). -The #GByteArray struct allows access to the public fields of a #GByteArray. +The GByteArray struct allows access to the public fields of a GByteArray. @data: a pointer to the element data. The data may be moved as elements are @@ -159,7 +159,7 @@ Sets the size of the #GByteArray, expanding it if necessary. Frees the memory allocated by the #GByteArray. -If free_segment is %TRUE it frees the actual byte data. +If @free_segment is %TRUE it frees the actual byte data. @array: a #GByteArray. diff --git a/docs/reference/glib/tmpl/arrays_pointer.sgml b/docs/reference/glib/tmpl/arrays_pointer.sgml index 74dc81bf1..48f869b31 100644 --- a/docs/reference/glib/tmpl/arrays_pointer.sgml +++ b/docs/reference/glib/tmpl/arrays_pointer.sgml @@ -38,12 +38,12 @@ To set the size of a pointer array, use g_ptr_array_set_size(). To free a pointer array, use g_ptr_array_free(). -Using a GPtrArray. +Using a <structname>GPtrArray</structname>. GPtrArray *gparray; gchar *string1 = "one", *string2 = "two", *string3 = "three"; - gparray = g_ptr_array_new (); + gparray = g_ptr_array_new (); g_ptr_array_add (gparray, (gpointer) string1); g_ptr_array_add (gparray, (gpointer) string2); g_ptr_array_add (gparray, (gpointer) string3); @@ -63,14 +63,10 @@ To free a pointer array, use g_ptr_array_free(). Contains the public fields of a pointer array. -The pdata field points to the array of pointers, -which may as when the array grows. -The len field is the number of pointers in the -array. -@pdata: -@len: +@pdata: points to the array of pointers, which may be moved when the array grows. +@len: number of pointers in the array. diff --git a/docs/reference/glib/tmpl/caches.sgml b/docs/reference/glib/tmpl/caches.sgml index 887d4674d..99c344b68 100644 --- a/docs/reference/glib/tmpl/caches.sgml +++ b/docs/reference/glib/tmpl/caches.sgml @@ -10,10 +10,10 @@ A #GCache allows sharing of complex data structures, in order to save system resources. -GTK+ uses a #GCache for both GtkStyles and GdkGCs. These consume a lot of -resources, so a #GCache is used to see if a GtkStyle or GdkGC with the +GTK+ uses a #GCache for #GtkStyles; GDK uses one for #GdkGCs. These consume a lot of +resources, so a #GCache is used to see if a #GtkStyle or #GdkGC with the required properties already exists. If it does, then the existing -GtkStyle or GdkGC is used instead of creating a new one. +object is used instead of creating a new one. #GCache uses keys and values. @@ -29,7 +29,7 @@ A #GCache value is the actual resource. The #GCache struct is an opaque data structure containing information about -a #GCache. It should only be accesssed via the following functions. +a #GCache. It should only be accessed via the following functions. diff --git a/docs/reference/glib/tmpl/completion.sgml b/docs/reference/glib/tmpl/completion.sgml index b2d9a037d..4a0cd6b78 100644 --- a/docs/reference/glib/tmpl/completion.sgml +++ b/docs/reference/glib/tmpl/completion.sgml @@ -35,20 +35,13 @@ a different #GCompletionStrncmpFunc in g_completion_set_compare(). The data structure used for automatic completion. -items is the list of target items (strings -or data structures). -func is the function called to get the string -associated with a target item. It is %NULL if the target items are strings. -prefix is the last prefix passed to -g_completion_complete(). -cache is the list of items which begin with -prefix. -@items: -@func: -@prefix: -@cache: +@items: list of target items (strings or data structures). +@func: function which is called to get the string associated with a target + item. It is %NULL if the target items are strings. +@prefix: the last prefix passed to g_completion_complete(). +@cache: the list of items which begin with @prefix. @strncmp_func: diff --git a/docs/reference/glib/tmpl/conversions.sgml b/docs/reference/glib/tmpl/conversions.sgml index cc0affc2b..b6ffa55b7 100644 --- a/docs/reference/glib/tmpl/conversions.sgml +++ b/docs/reference/glib/tmpl/conversions.sgml @@ -2,7 +2,7 @@ Character Set Conversion -convert strings between different character sets using iconv() +convert strings between different character sets using iconv(). diff --git a/docs/reference/glib/tmpl/datalist.sgml b/docs/reference/glib/tmpl/datalist.sgml index 063639804..60c2bf418 100644 --- a/docs/reference/glib/tmpl/datalist.sgml +++ b/docs/reference/glib/tmpl/datalist.sgml @@ -15,7 +15,7 @@ The #GQuark methods are quicker, since the strings have to be converted to Data lists are used in GTK+ for associating arbitrary data with -GtkObjects, using gtk_object_set_data() and related functions. +#GtkObjects, using gtk_object_set_data() and related functions. diff --git a/docs/reference/glib/tmpl/date.sgml b/docs/reference/glib/tmpl/date.sgml index 688480dd9..5b27683a7 100644 --- a/docs/reference/glib/tmpl/date.sgml +++ b/docs/reference/glib/tmpl/date.sgml @@ -20,7 +20,7 @@ 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 -can keep both a Julian and Day-Month-Year representation of the date, +can keep both a Julian and day-month-year representation of the date, since some calculations are much easier with one representation or the other. A Julian representation is simply a count of days since some fixed day in the past; for #GDate the fixed day is January 1, 1 AD. @@ -47,7 +47,7 @@ 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 DMY or only the Julian +struct. Often only the day-month-year or only the Julian representation is valid. Sometimes neither is valid. Use the API. @@ -75,7 +75,7 @@ code readability. Represents a precise time, with seconds and microseconds. Same as the struct timeval returned by the -gettimeofday() UNIX call. +gettimeofday() Unix call. @tv_sec: seconds. @@ -231,7 +231,7 @@ represent an existing day). Free the return value with g_date_free(). Like g_date_new(), but also sets the value of the date. Assuming the -day/month/year triplet you pass in represents an existing day, the +day-month-year triplet you pass in represents an existing day, the returned date will be valid. @@ -685,7 +685,7 @@ though there is a 16-bit limit to what #GDate will understand. -Returns %TRUE if the day/month/year triplet forms a valid, existing day +Returns %TRUE if the day-month-year triplet forms a valid, existing day in the range of days #GDate understands (Year 1 or later, no more than a few thousand years in the future). diff --git a/docs/reference/glib/tmpl/error_reporting.sgml b/docs/reference/glib/tmpl/error_reporting.sgml index 56842db51..336dee631 100644 --- a/docs/reference/glib/tmpl/error_reporting.sgml +++ b/docs/reference/glib/tmpl/error_reporting.sgml @@ -2,8 +2,7 @@ Error Reporting - -System for reporting errors +a system for reporting errors. @@ -11,15 +10,15 @@ System for reporting errors 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 +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 +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 @@ -39,12 +38,12 @@ This is why most functions in GLib and GTK+ do not use the #GError facility. Functions that can fail take a return location for a #GError as their last argument. For example: - + gchar* g_file_get_contents (const gchar *filename, GError **error); - + If you pass a non-%NULL value for the error argument, it should point to a location where an error can be placed. For example: - + gchar *contents; GError *err = NULL; contents = g_file_get_contents ("foo.txt", &err); @@ -61,7 +60,7 @@ else /* Use file contents */ g_assert (contents != NULL); } - + Note that err != NULL in this example is a reliable indicator of whether g_file_get_contents() failed. Also, g_file_get_contents() uses the @@ -73,13 +72,13 @@ all functions use this convention). Because g_file_get_contents() returns %NULL 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: - + contents = g_file_get_contents ("foo.txt", NULL); /* ignore errors */ if (contents != NULL) /* no error occurred */ ; else /* error */ ; - + @@ -103,7 +102,7 @@ When implementing a function that can report errors, the basic tool is g_set_error(). Typically, if a fatal error occurs you want to g_set_error(), then return immediately. g_set_error() does nothing if the error location passed to it is %NULL. Here's an example: - + gint foo_open_file (GError **error) { @@ -123,7 +122,7 @@ foo_open_file (GError **error) else return fd; } - + @@ -131,7 +130,7 @@ Things are somewhat more complicated if you yourself call another function that can report a #GError. If the sub-function indicates fatal errors in some way other than reporting a #GError, such as by returning %TRUE on success, you can simply do the following: - + gboolean my_function_that_can_fail (GError **err) { @@ -147,14 +146,14 @@ my_function_that_can_fail (GError **err) /* otherwise continue, no error occurred */ g_assert (err == NULL || *err == NULL); } - + If the sub-function does not indicate errors other than by reporting a #GError, you need to create a temporary #GError since the passed-in one may be %NULL. g_propagate_error() is intended for use in this case. - + gboolean my_function_that_can_fail (GError **err) { @@ -168,7 +167,7 @@ my_function_that_can_fail (GError **err) if (tmp_error != NULL) { /* store tmp_error in err, if err != NULL, - * otherwise call g_error_free() on tmp_error + * otherwise call g_error_free() on tmp_error */ g_propagate_error (err, tmp_error); return FALSE; @@ -176,12 +175,12 @@ my_function_that_can_fail (GError **err) /* otherwise continue, no error occurred */ } - + Error pileups are always a bug. For example, this code is incorrect: - + gboolean my_function_that_can_fail (GError **err) { @@ -199,7 +198,7 @@ my_function_that_can_fail (GError **err) return FALSE; } } - + 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 @@ -207,7 +206,7 @@ calling function. Note that passing %NULL for the error location is 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() are not fatal to my_function_that_can_fail(): - + gboolean my_function_that_can_fail (GError **err) { @@ -226,7 +225,7 @@ my_function_that_can_fail (GError **err) return FALSE; } } - + diff --git a/docs/reference/glib/tmpl/fileutils.sgml b/docs/reference/glib/tmpl/fileutils.sgml index c9ae8e8b5..9d71dedb1 100644 --- a/docs/reference/glib/tmpl/fileutils.sgml +++ b/docs/reference/glib/tmpl/fileutils.sgml @@ -17,9 +17,9 @@ various file-related functions. Values corresponding to errno codes returned from file operations -on UNIX. Unlike errno codes, #GFileError values are available on +on Unix. Unlike errno codes, #GFileError values are available on all systems, even Windows. The exact meaning of each code depends on what -sort of file operation you were performing; the UNIX documentation +sort of file operation you were performing; the Unix documentation gives more details. The following error code descriptions come from the GNU C Library manual, and are under the copyright of that manual. diff --git a/docs/reference/glib/tmpl/hash_tables.sgml b/docs/reference/glib/tmpl/hash_tables.sgml index 13a81a249..31b778597 100644 --- a/docs/reference/glib/tmpl/hash_tables.sgml +++ b/docs/reference/glib/tmpl/hash_tables.sgml @@ -53,7 +53,7 @@ To destroy a #GHashTable use g_hash_table_destroy(). -The #GHashTable struct is an opaque data structure to represent a +The GHashTable struct is an opaque data structure to represent a Hash Table. It should only be accessed via the following functions. @@ -289,7 +289,7 @@ parameter, when using pointers as keys in a #GHashTable. Converts a gpointer to a hash value. It can be passed to g_hash_table_new() as the @hash_func parameter, when -using gpointer values as keys in a #GHashTable. +using pointers as keys in a #GHashTable. @v: a gpointer key. @@ -313,7 +313,7 @@ parameter, when using pointers to integers as keys in a #GHashTable. Converts a pointer to a #gint to a hash value. It can be passed to g_hash_table_new() as the @hash_func parameter, when -using pointers to #gint values as keys in a #GHashTable. +using pointers to integers values as keys in a #GHashTable. @v: a pointer to a #gint key. diff --git a/docs/reference/glib/tmpl/hooks.sgml b/docs/reference/glib/tmpl/hooks.sgml index de5f5c273..49b1be5a8 100644 --- a/docs/reference/glib/tmpl/hooks.sgml +++ b/docs/reference/glib/tmpl/hooks.sgml @@ -19,53 +19,18 @@ and the list of hook functions can be invoked. - - - - - - -#guint seq_id; -the next free #GHook id. - - - -#guint hook_size; -the size of the #GHookList elements, in bytes. - - - -#guint is_setup : 1; -1 if the #GHookList has been initialized. - - - -#GHook *hooks; -the first #GHook element in the list. - - - -#GMemChunk *hook_memchunk; -the #GMemChunk used for allocating the #GHook elements. - - - -#GHookFinalizeFunc finalize_hook; -the function to call to finalize a #GHook element. -The default behaviour is to call the hooks destroy -function. - - - - +The GHookList struct represents a +list of hook functions. -@seq_id: -@hook_size: -@is_setup: -@hooks: -@hook_memchunk: -@finalize_hook: +@seq_id: the next free #GHook id. +@hook_size: the size of the #GHookList elements, in bytes. +@is_setup: 1 if the #GHookList has been initialized. +@hooks: the first #GHook element in the list. +@hook_memchunk: the #GMemChunk used for allocating the #GHook elements. +@finalize_hook: the function to call to finalize a #GHook element. The +default behaviour is to call the hooks destroy function. + @@ -79,65 +44,22 @@ list of hooks gets finalized. - - - - - - -#gpointer data; -data which is passed to func when this hook is invoked. - - - -#GHook *next; -pointer to the next hook in the list. - - - -#GHook *prev; -pointer to the previous hook in the list. - - - -#guint ref_count; -the reference count of this hook. - - - -#guint hook_id; -the id of this hook, which is unique within its list. - - - -#guint flags; -flags which are set for this hook. See #GHookFlagMask for -predefined flags. - - - -#gpointer func; -the function to call when this hook is invoked. The possible -signatures for this function are #GHookFunc and #GHookCheckFunc. - - - -#GDestroyNotify destroy; -the default finalize_hook function of a -#GHookList calls this member of the hook that is being finalized. - - - +The GHook struct represents a single hook +function in a #GHookList. -@data: -@next: -@prev: -@ref_count: -@hook_id: -@flags: -@func: -@destroy: +@data: data which is passed to func when this hook is invoked. +@next: pointer to the next hook in the list. +@prev: pointer to the previous hook in the list. +@ref_count: the reference count of this hook. +@hook_id: the id of this hook, which is unique within its list. +@flags: flags which are set for this hook. See #GHookFlagMask for +predefined flags. +@func: the function to call when this hook is invoked. The possible +signatures for this function are #GHookFunc and #GHookCheckFunc. +@destroy: the default finalize_hook function of a +#GHookList calls this member of the hook that is being finalized. + diff --git a/docs/reference/glib/tmpl/macros.sgml b/docs/reference/glib/tmpl/macros.sgml index 4912c67b8..c272600c2 100644 --- a/docs/reference/glib/tmpl/macros.sgml +++ b/docs/reference/glib/tmpl/macros.sgml @@ -53,8 +53,8 @@ BeOS-specific code in "#ifdef G_OS_BEOS". -This macro is defined only on UNIX. So you can bracket -UNIX-specific code in "#ifdef G_OS_UNIX". +This macro is defined only on Unix. So you can bracket +Unix-specific code in "#ifdef G_OS_UNIX". diff --git a/docs/reference/glib/tmpl/macros_misc.sgml b/docs/reference/glib/tmpl/macros_misc.sgml index 16d2ac28c..bdccfc629 100644 --- a/docs/reference/glib/tmpl/macros_misc.sgml +++ b/docs/reference/glib/tmpl/macros_misc.sgml @@ -42,7 +42,8 @@ only one statement is expected by the compiler. Used (along with #G_END_DECLS) to bracket header files. If the -compiler in use is a C++ compiler, adds 'extern "C"' around the header. +compiler in use is a C++ compiler, adds extern "C" +around the header. @@ -92,16 +93,17 @@ Accepts a macro or a string and converts it into a string. -Expands to __extension__ when GNU C is used as the compiler. -This simply tells GNU C not to warn about the following non-standard code -when compiling with the -pedantic option. +Expands to __extension__ when gcc is +used as the compiler. +This simply tells gcc not to warn about the following non-standard code +when compiling with the option. -Expands to the GNU C const function attribute if the compiler is GNU C. +Expands to the GNU C const function attribute if the compiler is gcc. Declaring a function as const enables better optimization of the function. A const function doesn't examine any values except its parameters, and has no effects except its return value. @@ -118,7 +120,7 @@ for a const function to return void. -Expands to the GNU C noreturn function attribute if the compiler is GNU C. +Expands to the GNU C noreturn function attribute if the compiler is gcc. It is used for declaring functions which never return. It enables optimization of the function, and avoids possible compiler warnings. See the GNU C documentation for details. @@ -128,7 +130,7 @@ warnings. See the GNU C documentation for details. -Expands to the GNU C unused function attribute if the compiler is GNU C. +Expands to the GNU C unused function attribute if the compiler is gcc. It is used for declaring functions which may never be used. It avoids possible compiler warnings. See the GNU C documentation for details. @@ -137,7 +139,7 @@ It avoids possible compiler warnings. See the GNU C documentation for details. -Expands to the GNU C pure function attribute if the compiler is GNU C. +Expands to the GNU C pure function attribute if the compiler is gcc. Declaring a function as pure enables better optimization of the function. A pure function has no effects except its return value and the return value depends only on the parameters and/or global variables. @@ -148,7 +150,7 @@ See the GNU C documentation for details. -Expands to the GNU C format function attribute if the compiler is GNU C. +Expands to the GNU C format function attribute if the compiler is gcc. This is used for declaring functions which take a variable number of arguments, with the same syntax as printf(). It allows the compiler to type-check the arguments passed to the function. @@ -168,7 +170,7 @@ gint g_snprintf (gchar *string, -Expands to the GNU C format function attribute if the compiler is GNU C. +Expands to the GNU C format function attribute if the compiler is gcc. This is used for declaring functions which take a variable number of arguments, with the same syntax as scanf(). It allows the compiler to type-check the arguments passed to the function. @@ -182,8 +184,8 @@ See the GNU C documentation for details. -Expands to the GNU C format_arg function attribute if the compiler is GNU C. -The format_arg function attribute specifies that a function takes a format +Expands to the GNU C format_arg function attribute if the compiler is gcc. +This function attribute specifies that a function takes a format string for a printf(), scanf(), strftime() or strfmon() style function and modifies it, so that the result can be passed to a @@ -203,7 +205,7 @@ gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2); Expands to the GNU C __FUNCTION__ variable if the -compiler is GNU C, or "" if it isn't. The GNU C +compiler is gcc, or "" if it isn't. The GNU C __FUNCTION__ variable contains the name of the current function. See the GNU C documentation for details. @@ -213,7 +215,7 @@ current function. See the GNU C documentation for details. Expands to the GNU C __PRETTY_FUNCTION__ variable -if the compiler is GNU C, or "" if it isn't. +if the compiler is gcc, or "" if it isn't. The GNU C __PRETTY_FUNCTION__ variable contains the name of the current function. For a C program this is the same as the __FUNCTION__ variable but for C++ it also includes @@ -225,8 +227,9 @@ GNU C documentation for details. -Expands to the GNU C no_instrument_function function attribute if -the compiler is GNU C. Functions with this attribute will not be +Expands to the GNU C no_instrument_function function +attribute if the compiler is gcc. Functions with this +attribute will not be instrumented for profiling, when the compiler is called with the option. See the GNU C documentation for details. diff --git a/docs/reference/glib/tmpl/main.sgml b/docs/reference/glib/tmpl/main.sgml index d7c0e86bc..46a010715 100644 --- a/docs/reference/glib/tmpl/main.sgml +++ b/docs/reference/glib/tmpl/main.sgml @@ -230,7 +230,7 @@ It is not used within GLib or GTK+. Use this for default priority event sources. In GLib this priority is used when adding timeout functions with g_timeout_add(). -In GDK this priority is used for events from the X Windows server. +In GDK this priority is used for events from the X server. @@ -593,7 +593,7 @@ g_main_context_set_poll_func() for full details. #gint fd; -the file descriptor to poll (or a HANDLE on Win32 platforms). +the file descriptor to poll (or a HANDLE on Win32 platforms). @@ -640,9 +640,9 @@ event sources in a generic manner. Called before all the file descriptors are polled. If the source can determine that it is ready here (without waiting for the -results of the poll() call) it should return %TRUE. +results of the poll() call) it should return %TRUE. It can also return a @timeout value which should be the maximum timeout -(in milliseconds) which should be passed to the poll() call. +(in milliseconds) which should be passed to the poll() call. The actual timeout used will be -1 if all sources returned -1, or it will be the minimum of all the @timeout values returned which were >= 0. diff --git a/docs/reference/glib/tmpl/markup.sgml b/docs/reference/glib/tmpl/markup.sgml index d2e27c9fb..58ac77988 100644 --- a/docs/reference/glib/tmpl/markup.sgml +++ b/docs/reference/glib/tmpl/markup.sgml @@ -2,13 +2,12 @@ Simple XML Subset Parser - -Parses a subset of XML +parses a subset of XML. The "GMarkup" parser is intended to parse a simple markup format -that's a subset of XML format. This is a small, efficient, easy-to-use +that's a subset of XML. This is a small, efficient, easy-to-use parser. It should not be used if you expect to interoperate with other applications generating full-scale XML. However, it's very useful for application data files, config files, etc. where you know your diff --git a/docs/reference/glib/tmpl/memory.sgml b/docs/reference/glib/tmpl/memory.sgml index b20aa3f82..f83043fa9 100644 --- a/docs/reference/glib/tmpl/memory.sgml +++ b/docs/reference/glib/tmpl/memory.sgml @@ -124,12 +124,12 @@ If @mem is %NULL it simply returns. Allocates @size bytes on the stack; these bytes will be freed when the current -stack frame is cleaned up. This macro essentially just wraps the alloca(3) function -present on most unix variants. Thus it provides the same advantages and pitfalls -as alloca(): +stack frame is cleaned up. This macro essentially just wraps the +alloca() function present on most Unix variants. +Thus it provides the same advantages and pitfalls as alloca(): - + alloca() is very fast, as on most systems it's implemented by just adjusting + + alloca() is very fast, as on most systems it's implemented by just adjusting the stack pointer register. @@ -139,17 +139,17 @@ as alloca(): - Allocation sizes have to fit into the current stack frame. For instance in a threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes, - so be sparse with alloca() uses. + so be sparse with alloca() uses. - Allocation failure due to insufficient stack space is not indicated with a %NULL - return like e.g. with malloc(3). Instead, most systems probably handle it the same + return like e.g. with malloc(). Instead, most systems probably handle it the same way as out of stack space situations from infinite function recursion, i.e. with a segmentation fault. - - Special care has to be taken when mixing alloca(3) with GCC variable sized arrays. - Stack space allocated with alloca(3) in the same scope as a variable sized array + - Special care has to be taken when mixing alloca() with GNU C variable sized arrays. + Stack space allocated with alloca() in the same scope as a variable sized array will be freed together with the variable sized array upon exit of that scope, and not upon exit of the enclosing function scope. @@ -216,8 +216,7 @@ if it exists, should be prior to any use of GLib. 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() +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 diff --git a/docs/reference/glib/tmpl/memory_chunks.sgml b/docs/reference/glib/tmpl/memory_chunks.sgml index 2f33963b9..c089a0850 100644 --- a/docs/reference/glib/tmpl/memory_chunks.sgml +++ b/docs/reference/glib/tmpl/memory_chunks.sgml @@ -95,7 +95,7 @@ To help debug memory chunks, use g_mem_chunk_info() and g_mem_chunk_print(). GRealArray *array; /* Create a GMemChunk to hold GRealArray structures, using the - g_mem_chunk_create() convenience macro. We want 1024 atoms in each + g_mem_chunk_create() convenience macro. We want 1024 atoms in each memory block, and we want to be able to free individual atoms. */ array_mem_chunk = g_mem_chunk_create (GRealArray, 1024, G_ALLOC_AND_FREE); diff --git a/docs/reference/glib/tmpl/messages.sgml b/docs/reference/glib/tmpl/messages.sgml index 2b8591235..ed7c4ad53 100644 --- a/docs/reference/glib/tmpl/messages.sgml +++ b/docs/reference/glib/tmpl/messages.sgml @@ -32,8 +32,7 @@ But be careful not to define it in any public header files. For example, GTK+ uses this in its Makefile.am: -INCLUDES = \ - -DG_LOG_DOMAIN=\"Gtk\" +INCLUDES = -DG_LOG_DOMAIN=\"Gtk\" @@ -112,7 +111,7 @@ documentation. A convenience function/macro to log a normal message. -@...: +@...: the parameters to insert into the format string. @format: the message format. See the printf() documentation. @@ -124,7 +123,7 @@ documentation. A convenience function/macro to log a warning message. -@...: format string, followed by parameters to insert into the format string (as with printf()) +@...: format string, followed by parameters to insert into the format string (as with printf()) @@ -136,7 +135,7 @@ warnings exit the program, then use g_critical() for fatal errors, for example. -@...: format string, followed by parameters to insert into the format string (as with printf()) +@...: format string, followed by parameters to insert into the format string (as with printf()) @@ -149,7 +148,7 @@ expect. Using this function indicates a bug in your program, i.e. an assertion failure. -@...: +@...: the parameters to insert into the format string. @format: the message format. See the printf() documentation. @@ -160,11 +159,11 @@ documentation. Sets the log handler for a domain and a set of log levels. To handle fatal and recursive messages the @log_levels parameter -must be combined with the G_LOG_FLAG_FATAL and G_LOG_FLAG_RECURSIVE bit flags. +must be combined with the #G_LOG_FLAG_FATAL and #G_LOG_FLAG_RECURSIVE bit flags. -Note that since the G_LOG_LEVEL_ERROR log level is always fatal, if you want -to set a handler for this log level you must combine it with G_LOG_FLAG_FATAL. +Note that since the #G_LOG_LEVEL_ERROR log level is always fatal, if you want +to set a handler for this log level you must combine it with #G_LOG_FLAG_FATAL. @@ -250,6 +249,6 @@ stderr is used for levels %G_LOG_LEVEL_ERROR, %G_LOG_LEVEL_CRITICAL, and @log_domain: the log domain of the message. @log_level: the level of the message. @message: the message. -@unused_data: data passed from g_log which is unused. +@unused_data: data passed from g_log() which is unused. diff --git a/docs/reference/glib/tmpl/misc_utils.sgml b/docs/reference/glib/tmpl/misc_utils.sgml index 2b3892665..4540eeb6f 100644 --- a/docs/reference/glib/tmpl/misc_utils.sgml +++ b/docs/reference/glib/tmpl/misc_utils.sgml @@ -53,7 +53,7 @@ Gets the user name of the current user. -Gets the real name of the user. This comes from the user's entry in the +Gets the real name of the user. This usually comes from the user's entry in the passwd file. @@ -73,7 +73,8 @@ Gets the current user's home directory. Gets the directory to use for temporary files. This is found from inspecting the environment variables TMPDIR, TMP, and TEMP -in that order. If none of those are defined "/tmp" is returned. +in that order. If none of those are defined "/tmp" is returned on Unix and +"C:\" on Windows. @Returns: the directory to use for temporary files. @@ -123,7 +124,7 @@ The returned string should be freed when no longer needed. Returns %TRUE if the given @file_name is an absolute file name, i.e. it contains a full path from the root directory such as '/usr/local' -or 'C:/windows' on windows systems. +on Unix or 'C:\windows' on Windows systems. @file_name: a file name. @@ -133,7 +134,7 @@ or 'C:/windows' on windows systems. Returns a pointer into @file_name after the root component, i.e. after -the '/' in Unix or 'C:/' under Windows. If @file_name is not an absolute +the '/' in Unix or 'C:\' under Windows. If @file_name is not an absolute path it returns %NULL. @@ -245,7 +246,7 @@ The built-in array of primes ranges from 11 to 13845163 such that each prime is approximately 1.5-2 times the previous prime. -@num: a guint. +@num: a #guint. @Returns: the smallest prime number from a built-in array of primes which is larger than @num. diff --git a/docs/reference/glib/tmpl/modules.sgml b/docs/reference/glib/tmpl/modules.sgml index a3b1d3ad1..17488d1f2 100644 --- a/docs/reference/glib/tmpl/modules.sgml +++ b/docs/reference/glib/tmpl/modules.sgml @@ -199,7 +199,7 @@ It is passed the #GModule structure. Expands to the proper shared library suffix for the current platform without the leading dot. For the most Unices and Linux this is "so", -for some HPUX versions this is "sl" and for Windows this is "dll". +for some HP-UX versions this is "sl" and for Windows this is "dll". diff --git a/docs/reference/glib/tmpl/numerical.sgml b/docs/reference/glib/tmpl/numerical.sgml index 661a3baa8..2fdf4e2b0 100644 --- a/docs/reference/glib/tmpl/numerical.sgml +++ b/docs/reference/glib/tmpl/numerical.sgml @@ -2,8 +2,7 @@ Numerical Definitions - -Mathematical constants, and floating point decomposition. +mathematical constants, and floating point decomposition. @@ -17,7 +16,7 @@ The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign, mantissa and exponent of IEEE floats and doubles. These unions are defined as appropriate for a given platform. IEEE floats and doubles are supported (used for - storage) by at least intel, ppc and sparc, for reference: http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html + storage) by at least Intel, PPC and Sparc, for reference: http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html @@ -45,7 +44,7 @@ The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign, mantissa and exponent of IEEE floats and doubles. These unions are defined as appropriate for a given platform. IEEE floats and doubles are supported (used for - storage) by at least intel, ppc and sparc, for reference: + storage) by at least Intel, PPC and Sparc, for reference: http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html @@ -56,7 +55,7 @@ The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign, mantissa and exponent of IEEE floats and doubles. These unions are defined as appropriate for a given platform. IEEE floats and doubles are supported (used for - storage) by at least intel, ppc and sparc, for reference: + storage) by at least Intel, PPC and Sparc, for reference: http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html diff --git a/docs/reference/glib/tmpl/patterns.sgml b/docs/reference/glib/tmpl/patterns.sgml index d3de5db03..cba7870cf 100644 --- a/docs/reference/glib/tmpl/patterns.sgml +++ b/docs/reference/glib/tmpl/patterns.sgml @@ -2,8 +2,7 @@ Glob-style pattern matching - -Matches strings against patterns containing '*' (wildcard) and '?' (joker). +matches strings against patterns containing '*' (wildcard) and '?' (joker). diff --git a/docs/reference/glib/tmpl/queue.sgml b/docs/reference/glib/tmpl/queue.sgml index fc5bb53e8..99427edee 100644 --- a/docs/reference/glib/tmpl/queue.sgml +++ b/docs/reference/glib/tmpl/queue.sgml @@ -2,7 +2,7 @@ Double-ended Queues -double-ended queue data structure +double-ended queue data structure. diff --git a/docs/reference/glib/tmpl/shell.sgml b/docs/reference/glib/tmpl/shell.sgml index 34efec3e9..399aa4f57 100644 --- a/docs/reference/glib/tmpl/shell.sgml +++ b/docs/reference/glib/tmpl/shell.sgml @@ -2,7 +2,7 @@ Shell-related Utilities -shell-like commandline handling +shell-like commandline handling. diff --git a/docs/reference/glib/tmpl/spawn.sgml b/docs/reference/glib/tmpl/spawn.sgml index bee83a102..7e2b9e994 100644 --- a/docs/reference/glib/tmpl/spawn.sgml +++ b/docs/reference/glib/tmpl/spawn.sgml @@ -2,7 +2,7 @@ Spawning Processes -Process launching with fork()/exec() +process launching with fork()/exec(). diff --git a/docs/reference/glib/tmpl/string_utils.sgml b/docs/reference/glib/tmpl/string_utils.sgml index 15115c8d2..1955df837 100644 --- a/docs/reference/glib/tmpl/string_utils.sgml +++ b/docs/reference/glib/tmpl/string_utils.sgml @@ -122,11 +122,10 @@ an even better idea. -Portability wrapper that calls strlcat() on systems which have it, and emulates -strlcat() otherwise. Appends nul-terminated @src string to @dest, guaranteeing +Portability wrapper that calls strlcat() on systems which have it, and emulates it otherwise. Appends nul-terminated @src string to @dest, guaranteeing nul-termination for @dest. The total size of @dest won't exceed -@dest_size. Caveat: this is supposedly a more secure alternative to strcat() or -strncat(), but for real security g_strconcat() is harder to mess up. +@dest_size. Caveat: this is supposedly a more secure alternative to strcat() or +strncat(), but for real security g_strconcat() is harder to mess up. @dest: destination buffer, already containing one nul-terminated string @@ -230,12 +229,12 @@ documentation. Determines whether a character is alphanumeric. -Unlike the standard C library isalnum function, this only +Unlike the standard C library isalnum() function, this only recognizes standard ASCII letters and ignores the locale, returning %FALSE for all non-ASCII characters. Also unlike the standard -library function, this takes a char, not an int, so don't call it -on EOF but no need to cast to guchar before passing a possibly -non-ASCII character in. +library function, this takes a char, not an int, +so don't call it on %EOF but no need to cast to #guchar before passing a +possibly non-ASCII character in. @c: any character @@ -247,12 +246,12 @@ non-ASCII character in. Determines whether a character is alphabetic (i.e. a letter). -Unlike the standard C library isalpha function, this only +Unlike the standard C library isalpha() function, this only recognizes standard ASCII letters and ignores the locale, returning %FALSE for all non-ASCII characters. Also unlike the standard -library function, this takes a char, not an int, so don't call it -on EOF but no need to cast to guchar before passing a possibly -non-ASCII character in. +library function, this takes a char, not an int @c: any character @@ -264,12 +263,12 @@ non-ASCII character in. Determines whether a character is a control character. -Unlike the standard C library iscntrl function, this only +Unlike the standard C library iscntrl() function, this only recognizes standard ASCII control characters and ignores the locale, -returning%FALSE for all non-ASCII characters. Also unlike the standard -library function, this takes a char, not an int, so don't call it -on EOF but no need to cast to guchar before passing a possibly -non-ASCII character in. +returning %FALSE for all non-ASCII characters. Also unlike the standard +library function, this takes a char, not an int, +so don't call it on %EOF but no need to cast to #guchar before passing a +possibly non-ASCII character in. @c: any character @@ -281,9 +280,9 @@ non-ASCII character in. Determines whether a character is digit (0-9). -Unlike the standard C library isdigit function, -this takes a char, not an int, so don't call it -on EOF but no need to cast to guchar before passing a possibly +Unlike the standard C library isdigit() function, +this takes a char, not an int, so don't call it +on %EOF but no need to cast to #guchar before passing a possibly non-ASCII character in. @@ -296,12 +295,12 @@ non-ASCII character in. Determines whether a character is a printing character and not a space. -Unlike the standard C library isgraph function, this only -recognizes standard ASCII characters and ignores the locale, returning -%FALSE for all non-ASCII characters. Also unlike the standard -library function, this takes a char, not an int, so don't call it -on EOF but no need to cast to guchar before passing a possibly -non-ASCII character in. +Unlike the standard C library isgraph() function, +this only recognizes standard ASCII characters and ignores the locale, +returning %FALSE for all non-ASCII characters. Also unlike the standard +library function, this takes a char, not an int, +so don't call it on %EOF but no need to cast to #guchar before passing a +possibly non-ASCII character in. @c: any character @@ -313,12 +312,12 @@ non-ASCII character in. Determines whether a character is an ASCII lower case letter. -Unlike the standard C library islower function, this only -recognizes standard ASCII letters and ignores the locale, returning -%FALSE for all non-ASCII characters. Also unlike the standard -library function, this takes a char, not an int, so don't call it -on EOF but no need to worry about casting to guchar before passing -a possibly non-ASCII character in. +Unlike the standard C library islower() function, +this only recognizes standard ASCII letters and ignores the locale, +returning %FALSE for all non-ASCII characters. Also unlike the standard +library function, this takes a char, not an int, +so don't call it on %EOF but no need to worry about casting to #guchar +before passing a possibly non-ASCII character in. @c: any character @@ -330,12 +329,12 @@ a possibly non-ASCII character in. Determines whether a character is a printing character. -Unlike the standard C library isprint function, this only -recognizes standard ASCII characters and ignores the locale, returning -%FALSE for all non-ASCII characters. Also unlike the standard -library function, this takes a char, not an int, so don't call it -on EOF but no need to cast to guchar before passing a possibly -non-ASCII character in. +Unlike the standard C library isprint() function, +this only recognizes standard ASCII characters and ignores the locale, +returning %FALSE for all non-ASCII characters. Also unlike the standard +library function, this takes a char, not an int, +so don't call it on %EOF but no need to cast to #guchar before passing a +possibly non-ASCII character in. @c: any character @@ -347,12 +346,12 @@ non-ASCII character in. Determines whether a character is a punctuation character. -Unlike the standard C library ispunct function, this only -recognizes standard ASCII letters and ignores the locale, returning -%FALSE for all non-ASCII characters. Also unlike the standard -library function, this takes a char, not an int, so don't call it -on EOF but no need to cast to guchar before passing a possibly -non-ASCII character in. +Unlike the standard C library ispunct() function, +this only recognizes standard ASCII letters and ignores the locale, +returning %FALSE for all non-ASCII characters. Also unlike the standard +library function, this takes a char, not an int, +so don't call it on %EOF but no need to cast to #guchar before passing a +possibly non-ASCII character in. @c: any character @@ -364,12 +363,12 @@ non-ASCII character in. Determines whether a character is a white-space character. -Unlike the standard C library isspace function, this only -recognizes standard ASCII white-space and ignores the locale, returning -%FALSE for all non-ASCII characters. Also unlike the standard -library function, this takes a char, not an int, so don't call it -on EOF but no need to cast to guchar before passing a possibly -non-ASCII character in. +Unlike the standard C library isspace() function, +this only recognizes standard ASCII white-space and ignores the locale, +returning %FALSE for all non-ASCII characters. Also unlike the standard +library function, this takes a char, not an int, +so don't call it on %EOF but no need to cast to #guchar before passing a +possibly non-ASCII character in. @c: any character @@ -381,12 +380,12 @@ non-ASCII character in. Determines whether a character is an ASCII upper case letter. -Unlike the standard C library isupper function, this only -recognizes standard ASCII letters and ignores the locale, returning -%FALSE for all non-ASCII characters. Also unlike the standard -library function, this takes a char, not an int, so don't call it -on EOF but no need to worry about casting to guchar before passing -a possibly non-ASCII character in. +Unlike the standard C library isupper() function, +this only recognizes standard ASCII letters and ignores the locale, +returning %FALSE for all non-ASCII characters. Also unlike the standard +library function, this takes a char, not an int, +so don't call it on %EOF but no need to worry about casting to #guchar +before passing a possibly non-ASCII character in. @c: any character @@ -398,9 +397,9 @@ a possibly non-ASCII character in. Determines whether a character is a hexadecimal-digit character. -Unlike the standard C library isxdigit function, -this takes a char, not an int, so -don't call it on EOF but no need to cast to guchar before passing a +Unlike the standard C library isxdigit() function, +this takes a char, not an int, so +don't call it on %EOF but no need to cast to #guchar before passing a possibly non-ASCII character in. @@ -554,7 +553,8 @@ of the strings. The problem with g_strncasecmp() is that it does the comparison by -calling toupper()/tolower() on each byte. toupper()/tolower() are +calling toupper()/tolower() +on each byte. toupper()/tolower() are locale-specific and operate on single bytes. However, it is impossible to handle things correctly from an i18n standpoint by operating on bytes, since characters may be multibyte. Thus g_strncasecmp() is @@ -580,7 +580,7 @@ value if @s1 > @s2. Reverses all of the characters in a string. -For example, g_strreverse ("abcdef") will result in "fedcba". +For example, g_strreverse ("abcdef") will result in "fedcba". @string: the string to reverse. @@ -589,19 +589,17 @@ For example, g_strreverse ("abcdef") will result in "fedcba". -A good size for a buffer to be passed into g_ascii_dtostr. +A good size for a buffer to be passed into g_ascii_dtostr(). It is guaranteed to be enough for all output of that function on systems with - 64bit IEEE compatible doubles. + 64bit IEEE-compatible doubles. The typical usage would be something like: - - - + char buf[G_ASCII_DTOSTR_BUF_SIZE]; fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value)); - + @@ -694,7 +692,7 @@ standard delimiters defined in #G_STR_DELIMITERS. -The standard delimiters, used in #g_strdelimit. +The standard delimiters, used in g_strdelimit(). diff --git a/docs/reference/glib/tmpl/thread_pools.sgml b/docs/reference/glib/tmpl/thread_pools.sgml index f31bcc7a3..a13629a3e 100644 --- a/docs/reference/glib/tmpl/thread_pools.sgml +++ b/docs/reference/glib/tmpl/thread_pools.sgml @@ -2,7 +2,7 @@ Thread Pools -Pools of threads to execute work concurrently +pools of threads to execute work concurrently. diff --git a/docs/reference/glib/tmpl/threads.sgml b/docs/reference/glib/tmpl/threads.sgml index 6e1aa4f80..99060d4a1 100644 --- a/docs/reference/glib/tmpl/threads.sgml +++ b/docs/reference/glib/tmpl/threads.sgml @@ -158,7 +158,7 @@ really know what you are doing. g_thread_init() must not be called directly or indirectly as a -call-back from GLib. Also no mutexes may be currently locked, while +callback from GLib. Also no mutexes may be currently locked, while calling g_thread_init(). @@ -172,7 +172,7 @@ system is initialized, you can do that too: -if (!g_thread_supported ()) g_thread_init (NULL); +if (!g_thread_supported ()) g_thread_init (NULL); @@ -362,7 +362,7 @@ This functions returns the #GThread corresponding to the calling thread. Waits until @thread finishes, i.e. the function @func, as given -to g_thread_create, returns or g_thread_exit() is called by +to g_thread_create(), returns or g_thread_exit() is called by @thread. All resources of @thread including the #GThread struct are released. @thread must have been created with @joinable=%TRUE in g_thread_create(). The value returned by @func or given to @@ -375,7 +375,7 @@ g_thread_exit() by @thread is returned by this function. -Change the priority of @thread to @priority. +Changes the priority of @thread to @priority. @@ -394,7 +394,7 @@ being dependent on priorities. -Give way to other threads waiting to be scheduled. +Gives way to other threads waiting to be scheduled. @@ -407,7 +407,7 @@ to do that. So in general you shouldn't use that function. -Exit the current thread. If another thread is waiting for that thread +Exits the current thread. If another thread is waiting for that thread using g_thread_join() and the current thread is joinable, the waiting thread will be woken up and getting @retval as the return value of g_thread_join(). If the current thread is not joinable, @retval is @@ -440,9 +440,8 @@ in the function @func, as given to g_thread_create(). -Never call g_thread_exit from within a thread of a #GThreadPool, as -that will mess up the bookkeeping and lead to funny and unwanted -results. +Never call g_thread_exit() from within a thread of a #GThreadPool, as +that will mess up the bookkeeping and lead to funny and unwanted results. @@ -459,7 +458,7 @@ access. Take for example the following function: A function which will not work in a threaded environment - int give_me_next_number () + int give_me_next_number () { static int current_number = 0; @@ -482,7 +481,7 @@ access. A first naive implementation would be: The wrong way to write a thread-safe function - int give_me_next_number () + int give_me_next_number () { static int current_number = 0; int ret_val; @@ -513,13 +512,13 @@ not use such constructs in your own programs. One working solution is: /* this function must be called before any call to give_me_next_number () it must be called exactly once. */ - void init_give_me_next_number () + void init_give_me_next_number () { g_assert (give_me_next_number_mutex == NULL); give_me_next_number_mutex = g_mutex_new (); } - int give_me_next_number () + int give_me_next_number () { static int current_number = 0; int ret_val; @@ -650,14 +649,14 @@ Destroys @mutex. A #GStaticMutex works like a #GMutex, but it has one significant advantage. It doesn't need to be created at run-time like a #GMutex, but can be defined at compile-time. Here is a shorter, easier and -safer version of our give_me_next_number() example: +safer version of our give_me_next_number() example: -Using GStaticMutex to simplify thread-safe programming +Using <structname>GStaticMutex</structname> to simplify thread-safe programming - int give_me_next_number () + int give_me_next_number () { static int current_number = 0; int ret_val; @@ -802,11 +801,11 @@ variable you intent to protect with the lock. Look at our -Using the G_LOCK_* convenience macros +Using the %G_LOCK_* convenience macros G_LOCK_DEFINE (current_number); -int give_me_next_number () +int give_me_next_number () { static int current_number = 0; int ret_val; diff --git a/docs/reference/glib/tmpl/timers.sgml b/docs/reference/glib/tmpl/timers.sgml index 2ee0bfdd7..2cdb8f7a2 100644 --- a/docs/reference/glib/tmpl/timers.sgml +++ b/docs/reference/glib/tmpl/timers.sgml @@ -3,7 +3,7 @@ Timers -Keep track of elapsed time. +keep track of elapsed time. diff --git a/docs/reference/glib/tmpl/trees-binary.sgml b/docs/reference/glib/tmpl/trees-binary.sgml index 36af29ebb..d3838a86f 100644 --- a/docs/reference/glib/tmpl/trees-binary.sgml +++ b/docs/reference/glib/tmpl/trees-binary.sgml @@ -2,13 +2,13 @@ Balanced Binary Trees -a sorted collection of key/value pairs optimised for searching +a sorted collection of key/value pairs optimized for searching and traversing in order. The #GTree structure and its associated functions provide a sorted collection -of key/value pairs optimised for searching and traversing in order. +of key/value pairs optimized for searching and traversing in order. To create a new #GTree use g_tree_new(). @@ -42,7 +42,7 @@ To destroy a #GTree, use g_tree_destroy(). -The #GTree struct is an opaque data structure representing a +The GTree struct is an opaque data structure representing a Balanced Binary Tree. It should be accessed only by using the following functions. diff --git a/docs/reference/glib/tmpl/trees-nary.sgml b/docs/reference/glib/tmpl/trees-nary.sgml index ee8316690..9cd1767a0 100644 --- a/docs/reference/glib/tmpl/trees-nary.sgml +++ b/docs/reference/glib/tmpl/trees-nary.sgml @@ -51,16 +51,16 @@ g_node_destroy(). -The #GNode struct represents one node in a +The GNode struct represents one node in a N-ary Tree. The data field contains the actual data of the node. The next and prev -fields point to the node's siblings (a sibling is another #GNode with the +fields point to the node's siblings (a sibling is another GNode with the same parent). -The parent field points to the parent of the #GNode, -or is %NULL if the #GNode is the root of the tree. +The parent field points to the parent of the GNode, +or is %NULL if the GNode is the root of the tree. The children field points to the first child of the -#GNode. The other children are accessed by using the +GNode. The other children are accessed by using the next pointer of each child. diff --git a/docs/reference/glib/tmpl/type_conversion.sgml b/docs/reference/glib/tmpl/type_conversion.sgml index 5f36d5c39..41527e5cb 100644 --- a/docs/reference/glib/tmpl/type_conversion.sgml +++ b/docs/reference/glib/tmpl/type_conversion.sgml @@ -3,7 +3,7 @@ Type Conversion Macros -Portably storing integers in pointer variables. +portably storing integers in pointer variables. @@ -11,10 +11,10 @@ Many times GLib, GTK+, and other libraries allow you to pass "user data" to a callback, in the form of a void pointer. From time to time you want to pass an integer instead of a pointer. You could allocate an integer, with something like: - + int *ip = g_new (int, 1); *ip = 42; - + But this is inconvenient, and it's annoying to have to free the memory at some later time. @@ -22,20 +22,20 @@ memory at some later time. Pointers are always at least 32 bits in size (on all platforms GLib intends to support). Thus you can store at least 32-bit integer values in a pointer value. Naively, you might try this, but it's incorrect: - + gpointer p; int i; p = (void*) 42; i = (int) p; - + Again, that example was not correct, don't copy it. The problem is that on some systems you need to do this: - + gpointer p; int i; p = (void*) (long) 42; i = (int) (long) p; - + So GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. do the right thing on the current platform. diff --git a/docs/reference/glib/tmpl/unicode.sgml b/docs/reference/glib/tmpl/unicode.sgml index b9edb0dc3..0223c3f92 100644 --- a/docs/reference/glib/tmpl/unicode.sgml +++ b/docs/reference/glib/tmpl/unicode.sgml @@ -31,7 +31,7 @@ Convenience functions for converting between UTF-8 and the locale encoding. -A type which can hold any UCS-4 character code. +A type which can hold any UCS-4 character code. @@ -346,7 +346,7 @@ See Skips to the next character in a UTF-8 string. The string must be -valid; this macro is as fast as possible, and has zero error-checking. +valid; this macro is as fast as possible, and has no error-checking. You would use this macro to iterate over a string character by character. The macro returns the start of the next UTF-8 character. Before using this macro, use g_utf8_validate() to validate strings @@ -527,7 +527,7 @@ that may contain invalid UTF-8. -A #GNormalizeMode defines how a Unicode string is transformed in a canonical +Defines how a Unicode string is transformed in a canonical form, standardizing such issues as whether a character with an accent is represented as a base character and combining accent or as a single precomposed character. Unicode strings should generally be normalized before comparing them. diff --git a/docs/reference/glib/tmpl/warnings.sgml b/docs/reference/glib/tmpl/warnings.sgml index 2ecbed3fb..bcce91c9b 100644 --- a/docs/reference/glib/tmpl/warnings.sgml +++ b/docs/reference/glib/tmpl/warnings.sgml @@ -37,7 +37,7 @@ documentation. Sets the print handler. Any messages passed to g_print() will be output via the new handler. The default handler simply outputs the message to stdout. -By providing your own handler you can redirect the output, to a GTK +By providing your own handler you can redirect the output, to a GTK+ widget or a log file for example. @@ -74,7 +74,7 @@ documentation. Sets the handler for printing error messages. Any messages passed to g_printerr() will be output via the new handler. The default handler simply outputs the message to stderr. -By providing your own handler you can redirect the output, to a GTK +By providing your own handler you can redirect the output, to a GTK+ widget or a log file for example. @@ -172,7 +172,7 @@ The prompt is then shown again. If [P]roceed is selected, the function returns. -This function may cause different actions on non-unix platforms. +This function may cause different actions on non-Unix platforms. @prg_name: the program name, needed by gdb for the [S]tack trace option. @@ -186,7 +186,7 @@ Invokes gdb, which attaches to the current process and shows Called by g_on_error_query() when the [S]tack trace option is selected. -This function may cause different actions on non-unix platforms. +This function may cause different actions on non-Unix platforms. @prg_name: the program name, needed by gdb for the [S]tack trace option. diff --git a/docs/reference/glib/tmpl/windows.sgml b/docs/reference/glib/tmpl/windows.sgml index 774e4425e..26a92d836 100644 --- a/docs/reference/glib/tmpl/windows.sgml +++ b/docs/reference/glib/tmpl/windows.sgml @@ -2,7 +2,7 @@ Windows Compatibility Functions -Unix emulation on Windows +Unix emulation on Windows. @@ -16,7 +16,7 @@ Unix emulation on Windows -Provided for UNIX emulation on Windows; equivalent to UNIX +Provided for Unix emulation on Windows; equivalent to Unix macro %MAXPATHLEN, which is the maximum length of a filename (including full path). @@ -25,14 +25,14 @@ macro %MAXPATHLEN, which is the maximum length of a filename -Provided for UNIX emulation on Windows; process ID type. +Provided for Unix emulation on Windows; process ID type. -Provided for UNIX emulation on Windows; see documentation for pipe() -in any UNIX manual. +Provided for Unix emulation on Windows; see documentation for pipe() +in any Unix manual. @phandles: @@ -40,8 +40,8 @@ in any UNIX manual. -Provided for UNIX emulation on Windows; see documentation for ftruncate() -in any UNIX manual. +Provided for Unix emulation on Windows; see documentation for ftruncate() +in any Unix manual. @fd: diff --git a/glib/gconvert.c b/glib/gconvert.c index dfdea6c3b..be4bf1ea2 100644 --- a/glib/gconvert.c +++ b/glib/gconvert.c @@ -93,11 +93,11 @@ extern const char **_g_charset_get_aliases (const char *canonical_name); * @to_codeset: destination codeset * @from_codeset: source codeset * - * Same as the standard UNIX routine iconv_open(), but - * may be implemented via libiconv on UNIX flavors that lack + * Same as the standard Unix routine iconv_open(), but + * may be implemented via libiconv on Unix flavors that lack * a native implementation. * - * GLib provides g_convert() and g_locale_to_utf8() which are likely + * &GLib; provides g_convert() and g_locale_to_utf8() which are likely * more convenient than the raw iconv wrappers. * * Return value: a "conversion descriptor" @@ -143,11 +143,11 @@ g_iconv_open (const gchar *to_codeset, * @outbuf: converted output bytes * @outbytes_left: inout parameter, bytes available to fill in @outbuf * - * Same as the standard UNIX routine iconv(), but - * may be implemented via libiconv on UNIX flavors that lack + * Same as the standard Unix routine iconv(), but + * may be implemented via libiconv on Unix flavors that lack * a native implementation. * - * GLib provides g_convert() and g_locale_to_utf8() which are likely + * &GLib; provides g_convert() and g_locale_to_utf8() which are likely * more convenient than the raw iconv wrappers. * * Return value: count of non-reversible conversions, or -1 on error @@ -168,13 +168,13 @@ g_iconv (GIConv converter, * g_iconv_close: * @converter: a conversion descriptor from g_iconv_open() * - * Same as the standard UNIX routine iconv_close(), but - * may be implemented via libiconv on UNIX flavors that lack + * Same as the standard Unix routine iconv_close(), but + * may be implemented via libiconv on Unix flavors that lack * a native implementation. Should be called to clean up - * the conversion descriptor from iconv_open() when + * the conversion descriptor from g_iconv_open() when * you are done converting things. * - * GLib provides g_convert() and g_locale_to_utf8() which are likely + * &GLib; provides g_convert() and g_locale_to_utf8() which are likely * more convenient than the raw iconv wrappers. * * Return value: -1 on error, 0 on success @@ -226,11 +226,11 @@ open_converter (const gchar *to_codeset, * stored will the byte offset after the last valid * input sequence. * @bytes_written: the number of bytes stored in the output buffer (not - * including the terminating NULL). + * including the terminating nul). * @error: location to store the error occuring, or %NULL to ignore * errors. Any of the errors in #GConvertError may occur. * - * Convert a string from one character set to another. + * Converts a string from one character set to another. * * Return value: If the conversion was successful, a newly allocated * nul-terminated string, which must be freed with @@ -281,18 +281,18 @@ g_convert (const gchar *str, * @converter: conversion descriptor from g_iconv_open() * @bytes_read: location to store the number of bytes in the * input string that were successfully converted, or %NULL. - * Even if the conversion was succesful, this may be + * Even if the conversion was successful, this may be * less than @len if there were partial characters * at the end of the input. If the error * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value * stored will the byte offset after the last valid * input sequence. * @bytes_written: the number of bytes stored in the output buffer (not - * including the terminating NULL). + * including the terminating nul). * @error: location to store the error occuring, or %NULL to ignore * errors. Any of the errors in #GConvertError may occur. * - * Convert a string from one character set to another. + * Converts a string from one character set to another. * * Return value: If the conversion was successful, a newly allocated * nul-terminated string, which must be freed with @@ -407,21 +407,21 @@ g_convert_with_iconv (const gchar *str, * as Unicode escapes \x{XXXX} or \x{XXXXXX}. * @bytes_read: location to store the number of bytes in the * input string that were successfully converted, or %NULL. - * Even if the conversion was succesful, this may be + * Even if the conversion was successful, this may be * less than @len if there were partial characters * at the end of the input. * @bytes_written: the number of bytes stored in the output buffer (not - * including the terminating NULL). + * including the terminating nul). * @error: location to store the error occuring, or %NULL to ignore * errors. Any of the errors in #GConvertError may occur. * - * Convert a string from one character set to another, possibly + * Converts a string from one character set to another, possibly * including fallback sequences for characters not representable * in the output. Note that it is not guaranteed that the specification * for the fallback sequences in @fallback will be honored. Some * systems may do a approximate conversion from @from_codeset - * to @to_codeset in their iconv() functions, in which case GLib - * will simply return that approximate conversion. + * to @to_codeset in their iconv() functions, + * in which case &GLib; will simply return that approximate conversion. * * Return value: If the conversion was successful, a newly allocated * nul-terminated string, which must be freed with @@ -665,14 +665,14 @@ strdup_len (const gchar *string, * nul-terminated. * @bytes_read: location to store the number of bytes in the * input string that were successfully converted, or %NULL. - * Even if the conversion was succesful, this may be + * Even if the conversion was successful, this may be * less than @len if there were partial characters * at the end of the input. If the error * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value * stored will the byte offset after the last valid * input sequence. * @bytes_written: the number of bytes stored in the output buffer (not - * including the terminating NULL). + * including the terminating nul). * @error: location to store the error occuring, or %NULL to ignore * errors. Any of the errors in #GConvertError may occur. * @@ -805,14 +805,14 @@ g_locale_to_utf8 (const gchar *opsysstring, * nul-terminated. * @bytes_read: location to store the number of bytes in the * input string that were successfully converted, or %NULL. - * Even if the conversion was succesful, this may be + * Even if the conversion was successful, this may be * less than @len if there were partial characters * at the end of the input. If the error * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value * stored will the byte offset after the last valid * input sequence. * @bytes_written: the number of bytes stored in the output buffer (not - * including the terminating NULL). + * including the terminating nul). * @error: location to store the error occuring, or %NULL to ignore * errors. Any of the errors in #GConvertError may occur. * @@ -951,14 +951,14 @@ g_locale_from_utf8 (const gchar *utf8string, * nul-terminated. * @bytes_read: location to store the number of bytes in the * input string that were successfully converted, or %NULL. - * Even if the conversion was succesful, this may be + * Even if the conversion was successful, this may be * less than @len if there were partial characters * at the end of the input. If the error * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value * stored will the byte offset after the last valid * input sequence. * @bytes_written: the number of bytes stored in the output buffer (not - * including the terminating NULL). + * including the terminating nul). * @error: location to store the error occuring, or %NULL to ignore * errors. Any of the errors in #GConvertError may occur. * @@ -996,14 +996,14 @@ g_filename_to_utf8 (const gchar *opsysstring, * nul-terminated. * @bytes_read: location to store the number of bytes in the * input string that were successfully converted, or %NULL. - * Even if the conversion was succesful, this may be + * Even if the conversion was successful, this may be * less than @len if there were partial characters * at the end of the input. If the error * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value * stored will the byte offset after the last valid * input sequence. * @bytes_written: the number of bytes stored in the output buffer (not - * including the terminating NULL). + * including the terminating nul). * @error: location to store the error occuring, or %NULL to ignore * errors. Any of the errors in #GConvertError may occur. * @@ -1237,7 +1237,7 @@ g_unescape_uri_string (const gchar *escaped, * Converts an escaped UTF-8 encoded URI to a local filename in the * encoding used for filenames. * - * Return value: a newly allocated string holding the resulting + * Return value: a newly-allocated string holding the resulting * filename, or %NULL on an error. **/ gchar * @@ -1337,7 +1337,7 @@ g_filename_from_uri (const char *uri, * * Converts an absolute filename to an escaped UTF-8 encoded URI. * - * Return value: a newly allocated string holding the resulting + * Return value: a newly-allocated string holding the resulting * URI, or %NULL on an error. **/ gchar * diff --git a/glib/ghash.c b/glib/ghash.c index 2a121d736..bd1b63409 100644 --- a/glib/ghash.c +++ b/glib/ghash.c @@ -241,7 +241,7 @@ g_hash_table_lookup (GHashTable *hash_table, * is useful if you need to free the memory allocated for the original key, * for example before calling g_hash_table_remove(). * - * Return value: #TRUE if the key was found in the #GHashTable. + * Return value: %TRUE if the key was found in the #GHashTable. **/ gboolean g_hash_table_lookup_extended (GHashTable *hash_table, @@ -371,7 +371,7 @@ g_hash_table_replace (GHashTable *hash_table, * you have to make sure that any dynamically allocated values are freed * yourself. * - * Return value: #TRUE if the key was found and removed from the #GHashTable. + * Return value: %TRUE if the key was found and removed from the #GHashTable. **/ gboolean g_hash_table_remove (GHashTable *hash_table, @@ -407,7 +407,7 @@ g_hash_table_remove (GHashTable *hash_table, * Removes a key and its associated value from a #GHashTable without * calling the key and value destroy functions. * - * Return value: #TRUE if the key was found and removed from the #GHashTable. + * Return value: %TRUE if the key was found and removed from the #GHashTable. **/ gboolean g_hash_table_steal (GHashTable *hash_table, diff --git a/glib/grand.c b/glib/grand.c index efba9557c..39741a820 100644 --- a/glib/grand.c +++ b/glib/grand.c @@ -84,8 +84,8 @@ g_rand_new_with_seed (guint32 seed) * g_rand_new: * * Creates a new random number generator initialized with a seed taken - * either from /dev/urandom (if existing) or from the current time (as - * a fallback). + * either from /dev/urandom (if existing) or from + * the current time (as a fallback). * * Return value: the new #GRand. **/ @@ -165,7 +165,7 @@ g_rand_set_seed (GRand* rand, guint32 seed) * g_rand_int: * @rand: a #GRand. * - * Return the next random #guint32 from @rand equaly distributed over + * Returns the next random #guint32 from @rand equally distributed over * the range [0..2^32-1]. * * Return value: A random number. @@ -214,7 +214,7 @@ g_rand_int (GRand* rand) * @begin: lower closed bound of the interval. * @end: upper open bound of the interval. * - * Return the next random #gint32 from @rand equaly distributed over + * Returns the next random #gint32 from @rand equally distributed over * the range [@begin..@end-1]. * * Return value: A random number. @@ -264,7 +264,7 @@ g_rand_int_range (GRand* rand, gint32 begin, gint32 end) * g_rand_double: * @rand: a #GRand. * - * Return the next random #gdouble from @rand equaly distributed over + * Returns the next random #gdouble from @rand equally distributed over * the range [0..1). * * Return value: A random number. @@ -291,7 +291,7 @@ g_rand_double (GRand* rand) * @begin: lower closed bound of the interval. * @end: upper open bound of the interval. * - * Return the next random #gdouble from @rand equaly distributed over + * Returns the next random #gdouble from @rand equally distributed over * the range [@begin..@end). * * Return value: A random number. @@ -305,7 +305,7 @@ g_rand_double_range (GRand* rand, gdouble begin, gdouble end) /** * g_random_int: * - * Return a random #guint32 equaly distributed over the range + * Return a random #guint32 equally distributed over the range * [0..2^32-1]. * * Return value: A random number. @@ -328,7 +328,7 @@ g_random_int (void) * @begin: lower closed bound of the interval. * @end: upper open bound of the interval. * - * Return a random #gint32 equaly distributed over the range + * Returns a random #gint32 equally distributed over the range * [@begin..@end-1]. * * Return value: A random number. @@ -349,7 +349,7 @@ g_random_int_range (gint32 begin, gint32 end) /** * g_random_double: * - * Return a random #gdouble equaly distributed over the range [0..1). + * Returns a random #gdouble equally distributed over the range [0..1). * * Return value: A random number. **/ @@ -371,7 +371,7 @@ g_random_double (void) * @begin: lower closed bound of the interval. * @end: upper open bound of the interval. * - * Return a random #gdouble equaly distributed over the range [@begin..@end). + * Returns a random #gdouble equally distributed over the range [@begin..@end). * * Return value: A random number. **/ @@ -393,7 +393,7 @@ g_random_double_range (gdouble begin, gdouble end) * @seed: a value to reinitialize the global random number generator. * * Sets the seed for the global random number generator, which is used - * by te g_random_* functions, to @seed. + * by the g_random_* functions, to @seed. **/ void g_random_set_seed (guint32 seed) diff --git a/glib/gthreadpool.c b/glib/gthreadpool.c index 601022830..020a11961 100644 --- a/glib/gthreadpool.c +++ b/glib/gthreadpool.c @@ -251,15 +251,15 @@ g_thread_pool_start_thread (GRealThreadPool *pool, * * The parameter @exclusive determines, whether the thread pool owns * all threads exclusive or whether the threads are shared - * globally. If @exclusive is @TRUE, @max_threads threads are started + * globally. If @exclusive is %TRUE, @max_threads threads are started * immediately and they will run exclusively for this thread pool until - * it is destroyed by g_thread_pool_free(). If @exclusive is @FALSE, + * it is destroyed by g_thread_pool_free(). If @exclusive is %FALSE, * threads are created, when needed and shared between all * non-exclusive thread pools. This implies that @max_threads may not * be -1 for exclusive thread pools. * - * @error can be NULL to ignore errors, or non-NULL to report - * errors. An error can only occur, when @exclusive is set to @TRUE and + * @error can be %NULL to ignore errors, or non-%NULL to report + * errors. An error can only occur when @exclusive is set to %TRUE and * not all @max_threads threads could be created. * * Return value: the new #GThreadPool @@ -334,8 +334,8 @@ g_thread_pool_new (GFunc func, * in the queue until a thread in this pool finishes its previous task * and processes @data. * - * @error can be NULL to ignore errors, or non-NULL to report - * errors. An error can only occur, when a new thread couldn't be + * @error can be %NULL to ignore errors, or non-%NULL to report + * errors. An error can only occur when a new thread couldn't be * created. In that case @data is simply appended to the queue of work * to do. **/ @@ -379,12 +379,12 @@ g_thread_pool_push (GThreadPool *pool, * * A thread is never terminated while calling @func, as supplied by * g_thread_pool_new (). Instead the maximal number of threads only - * has effect for the allocation of new threads in g_thread_pool_push - * (). A new thread is allocated, whenever the number of currently + * has effect for the allocation of new threads in g_thread_pool_push(). + * A new thread is allocated, whenever the number of currently * running threads in @pool is smaller than the maximal number. * - * @error can be NULL to ignore errors, or non-NULL to report - * errors. An error can only occur, when a new thread couldn't be + * @error can be %NULL to ignore errors, or non-%NULL to report + * errors. An error can only occur when a new thread couldn't be * created. **/ void @@ -505,13 +505,13 @@ g_thread_pool_unprocessed (GThreadPool *pool) * * Frees all resources allocated for @pool. * - * If @immediate is #TRUE, no new task is processed for + * If @immediate is %TRUE, no new task is processed for * @pool. Otherwise @pool is not freed before the last task is * processed. Note however, that no thread of this pool is * interrupted, while processing a task. Instead at least all still * running threads can finish their tasks before the @pool is freed. * - * If @wait is #TRUE, the functions does not return before all tasks + * If @wait is %TRUE, the functions does not return before all tasks * to be processed (dependent on @immediate, whether all or only the * currently running) are ready. Otherwise the function returns immediately. * diff --git a/glib/gtree.c b/glib/gtree.c index ceea2f866..e2d717ed1 100644 --- a/glib/gtree.c +++ b/glib/gtree.c @@ -278,7 +278,7 @@ g_tree_destroy (GTree *tree) * Inserts a key/value pair into a #GTree. If the given key already exists * in the #GTree its corresponding value is set to the new value. If you * supplied a value_destroy_func when creating the #GTree, the old value is - * freed using that function. If you supplied a key_destroy_func when + * freed using that function. If you supplied a @key_destroy_func when * creating the #GTree, the passed key is freed using that function. * * The tree is automatically 'balanced' as new key/value pairs are added, @@ -308,9 +308,9 @@ g_tree_insert (GTree *tree, * * Inserts a new key and value into a #GTree similar to g_tree_insert(). * The difference is that if the key already exists in the #GTree, it gets - * replaced by the new key. If you supplied a value_destroy_func when + * replaced by the new key. If you supplied a @value_destroy_func when * creating the #GTree, the old value is freed using that function. If you - * supplied a key_destroy_func when creating the #GTree, the old key is + * supplied a @key_destroy_func when creating the #GTree, the old key is * freed using that function. * * The tree is automatically 'balanced' as new key/value pairs are added, @@ -340,7 +340,7 @@ g_tree_replace (GTree *tree, * Removes a key/value pair from a #GTree. * * If the #GTree was created using g_tree_new_full(), the key and value - * are freed using the supplied destroy_functions, otherwise you have to + * are freed using the supplied @destroy_functions, otherwise you have to * make sure that any dynamically allocated values are freed yourself. **/ void @@ -402,11 +402,11 @@ g_tree_lookup (GTree *tree, * @value: returns the value associated with the key. * * Looks up a key in the #GTree, returning the original key and the - * associated value and a gboolean which is TRUE if the key was found. This + * associated value and a #gboolean which is %TRUE if the key was found. This * is useful if you need to free the memory allocated for the original key, * for example before calling g_tree_remove(). * - * Return value: #TRUE if the key was found in the #GTree. + * Return value: %TRUE if the key was found in the #GTree. **/ gboolean g_tree_lookup_extended (GTree *tree, @@ -527,7 +527,7 @@ g_tree_traverse (GTree *tree, * To search for a specific value, you can use g_tree_foreach() or * g_tree_traverse(). * - * Return value: the value corresponding to the found key, or NULL if the key + * Return value: the value corresponding to the found key, or %NULL if the key * is not found. **/ gpointer