luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-02-07 19:35:50 +01:00
Code Issues Packages Projects Releases Wiki Activity

Documentation fixes.

Browse Source 
* 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.
This commit is contained in:
Matthias Clasen 2001-12-12 20:32:07 +00:00
parent 24608fc156
commit 3fa33317b7
51 changed files with 381 additions and 412 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
ChangeLog
View File

@ -1,3 +1,8 @@
2001-12-12 Matthias Clasen <matthiasc@poet.de>
* 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 <hidetoshi.tajima@sun.com>
* glib/libcharset/config.charset (os):

5
ChangeLog.pre-2-0
View File

@ -1,3 +1,8 @@
2001-12-12 Matthias Clasen <matthiasc@poet.de>
* 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 <hidetoshi.tajima@sun.com>
* glib/libcharset/config.charset (os):

5
ChangeLog.pre-2-10
View File

@ -1,3 +1,8 @@
2001-12-12 Matthias Clasen <matthiasc@poet.de>
* 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 <hidetoshi.tajima@sun.com>
* glib/libcharset/config.charset (os):

5
ChangeLog.pre-2-12
View File

@ -1,3 +1,8 @@
2001-12-12 Matthias Clasen <matthiasc@poet.de>
* 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 <hidetoshi.tajima@sun.com>
* glib/libcharset/config.charset (os):

5
ChangeLog.pre-2-2
View File

@ -1,3 +1,8 @@
2001-12-12 Matthias Clasen <matthiasc@poet.de>
* 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 <hidetoshi.tajima@sun.com>
* glib/libcharset/config.charset (os):

5
ChangeLog.pre-2-4
View File

@ -1,3 +1,8 @@
2001-12-12 Matthias Clasen <matthiasc@poet.de>
* 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 <hidetoshi.tajima@sun.com>
* glib/libcharset/config.charset (os):

5
ChangeLog.pre-2-6
View File

@ -1,3 +1,8 @@
2001-12-12 Matthias Clasen <matthiasc@poet.de>
* 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 <hidetoshi.tajima@sun.com>
* glib/libcharset/config.charset (os):

5
ChangeLog.pre-2-8
View File

@ -1,3 +1,8 @@
2001-12-12 Matthias Clasen <matthiasc@poet.de>
* 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 <hidetoshi.tajima@sun.com>
* glib/libcharset/config.charset (os):

23
docs/reference/ChangeLog
View File

@ -1,3 +1,26 @@
2001-12-12 Matthias Clasen <matthiasc@poet.de>
* 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 <hp@redhat.com>
* glib/tmpl/messages.sgml: improve g_log_set_handler docs

2
docs/reference/glib/tmpl/allocators.sgml
View File

@ -36,7 +36,7 @@ elements. Each must use separate allocators.
<!-- ##### STRUCT GAllocator ##### -->
<para>
The #GAllocator struct contains private data. and should only be accessed
The <structname>GAllocator</structname> struct contains private data. and should only be accessed
using the following functions.
</para>

4
docs/reference/glib/tmpl/arrays.sgml
View File

@ -31,7 +31,7 @@ To set the size of an array, use g_array_set_size().
To free an array, use g_array_free().
</para>
<example>
<title>Using a GArray to store gint values.</title>
<title>Using a <structname>GArray</structname> to store gint values.</title>
<programlisting>
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.
<example>
<title>Getting a pointer to an element in a GArray.</title>
<title>Getting a pointer to an element in a <structname>GArray</structname>.</title>
<programlisting>
EDayViewEvent *event;

14
docs/reference/glib/tmpl/arrays_byte.sgml
View File

@ -6,7 +6,7 @@ arrays of bytes, which grow automatically as elements are added.
<!-- ##### SECTION Long_Description ##### -->
<para>
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.
</para>
<para>
@ -17,19 +17,19 @@ To add elements to a #GByteArray, use g_byte_array_append(), and
g_byte_array_prepend().
</para>
<para>
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().
</para>
<para>
To free a GByteArray, use g_byte_array_free().
To free a #GByteArray, use g_byte_array_free().
</para>
<example>
<title>Using a GByteArray.</title>
<title>Using a <structname>GByteArray</structname>.</title>
<programlisting>
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().
<!-- ##### STRUCT GByteArray ##### -->
<para>
The #GByteArray struct allows access to the public fields of a #GByteArray.
The <structname>GByteArray</structname> struct allows access to the public fields of a <structname>GByteArray</structname>.
</para>
@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.
<!-- ##### FUNCTION g_byte_array_free ##### -->
<para>
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.
</para>
@array: a #GByteArray.

12
docs/reference/glib/tmpl/arrays_pointer.sgml
View File

@ -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().
</para>
<example>
<title>Using a GPtrArray.</title>
<title>Using a <structname>GPtrArray</structname>.</title>
<programlisting>
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().
<!-- ##### STRUCT GPtrArray ##### -->
<para>
Contains the public fields of a pointer array.
The <structfield>pdata</structfield> field points to the array of pointers,
which may as when the array grows.
The <structfield>len</structfield> field is the number of pointers in the
array.
</para>
@pdata:
@len:
@pdata: points to the array of pointers, which may be moved when the array grows.
@len: number of pointers in the array.
<!-- ##### FUNCTION g_ptr_array_new ##### -->
<para>

8
docs/reference/glib/tmpl/caches.sgml
View File

@ -10,10 +10,10 @@ A #GCache allows sharing of complex data structures, in order to save
system resources.
</para>
<para>
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.
</para>
<para>
#GCache uses keys and values.
@ -29,7 +29,7 @@ A #GCache value is the actual resource.
<!-- ##### STRUCT GCache ##### -->
<para>
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.
</para>

17
docs/reference/glib/tmpl/completion.sgml
View File

@ -35,20 +35,13 @@ a different #GCompletionStrncmpFunc in g_completion_set_compare().
<!-- ##### STRUCT GCompletion ##### -->
<para>
The data structure used for automatic completion.
<structfield>items</structfield> is the list of target items (strings
or data structures).
<structfield>func</structfield> is the function called to get the string
associated with a target item. It is %NULL if the target items are strings.
<structfield>prefix</structfield> is the last prefix passed to
g_completion_complete().
<structfield>cache</structfield> is the list of items which begin with
<structfield>prefix</structfield>.
</para>
@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:
<!-- ##### FUNCTION g_completion_new ##### -->

2
docs/reference/glib/tmpl/conversions.sgml
View File

@ -2,7 +2,7 @@
Character Set Conversion
<!-- ##### SECTION Short_Description ##### -->
convert strings between different character sets using <function>iconv()</function>
convert strings between different character sets using <function>iconv()</function>.
<!-- ##### SECTION Long_Description ##### -->
<para>

2
docs/reference/glib/tmpl/datalist.sgml
View File

@ -15,7 +15,7 @@ The #GQuark methods are quicker, since the strings have to be converted to
</para>
<para>
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.
</para>
<para>

10
docs/reference/glib/tmpl/date.sgml
View File

@ -20,7 +20,7 @@ time information; it represents a <emphasis>day</emphasis>.
<para>
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.
<para>
<emphasis>It is very important to use the API to access the #GDate
struct.</emphasis> Often only the DMY or only the Julian
struct.</emphasis> Often only the day-month-year or only the Julian
representation is valid. Sometimes neither is valid. Use the API.
</para>
@ -75,7 +75,7 @@ code readability.
<para>
Represents a precise time, with seconds and microseconds. Same as the
<structname>struct timeval</structname> returned by the
<function>gettimeofday()</function> UNIX call.
<function>gettimeofday()</function> Unix call.
</para>
@tv_sec: seconds.
@ -231,7 +231,7 @@ represent an existing day). Free the return value with g_date_free().
<!-- ##### FUNCTION g_date_new_dmy ##### -->
<para>
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.
</para>
@ -685,7 +685,7 @@ though there is a 16-bit limit to what #GDate will understand.
<!-- ##### FUNCTION g_date_valid_dmy ##### -->
<para>
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).
</para>

43
docs/reference/glib/tmpl/error_reporting.sgml
View File

@ -2,8 +2,7 @@
Error Reporting
<!-- ##### SECTION Short_Description ##### -->
System for reporting errors
a system for reporting errors.
<!-- ##### SECTION Long_Description ##### -->
@ -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
<emphasis>data type </emphasis> (the #GError object) and a <emphasis>set of
rules</emphasis>. If you use #GError incorrectly, then your code will not
<emphasis>data type</emphasis> (the #GError object) and a <emphasis>set of
rules.</emphasis> 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.
</para>
<para>
First and foremost: <emphasis>#GError should only be used to report
recoverable runtime errors, never to report programming errors</emphasis>. If
recoverable runtime errors, never to report programming errors.</emphasis> 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.
<para>
Functions that can fail take a return location for a #GError as their last argument.
For example:
<programlisting>
<informalexample><programlisting>
gchar* g_file_get_contents (const gchar *filename, GError **error);
</programlisting>
</programlisting></informalexample>
If you pass a non-%NULL value for the <literal>error</literal> argument, it should
point to a location where an error can be placed. For example:
<programlisting>
<informalexample><programlisting>
gchar *contents;
GError *err = NULL;
contents = g_file_get_contents ("foo.txt", &amp;err);
@ -61,7 +60,7 @@ else
/* Use file contents */
g_assert (contents != NULL);
}
</programlisting>
</programlisting></informalexample>
Note that <literal>err != NULL</literal> in this example is a
<emphasis>reliable</emphasis> 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 <literal>error</literal> argument:
<programlisting>
<informalexample><programlisting>
contents = g_file_get_contents ("foo.txt", NULL); /* ignore errors */
if (contents != NULL)
/* no error occurred */ ;
else
/* error */ ;
</programlisting>
</programlisting></informalexample>
</para>
<para>
@ -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:
<programlisting>
<informalexample><programlisting>
gint
foo_open_file (GError **error)
{
@ -123,7 +122,7 @@ foo_open_file (GError **error)
else
return fd;
}
</programlisting>
</programlisting></informalexample>
</para>
<para>
@ -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:
<programlisting>
<informalexample><programlisting>
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);
}
</programlisting>
</programlisting></informalexample>
</para>
<para>
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.
<programlisting>
<informalexample><programlisting>
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 */
}
</programlisting>
</programlisting></informalexample>
</para>
<para>
Error pileups are always a bug. For example, this code is incorrect:
<programlisting>
<informalexample><programlisting>
gboolean
my_function_that_can_fail (GError **err)
{
@ -199,7 +198,7 @@ my_function_that_can_fail (GError **err)
return FALSE;
}
}
</programlisting>
</programlisting></informalexample>
<literal>tmp_error</literal> should be checked immediately after
<function>sub_function_that_can_fail()</function>, and either cleared or propagated upward. The rule
is: <emphasis>after each error, you must either handle the error, or return it to the
@ -207,7 +206,7 @@ calling function</emphasis>. 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 <function>sub_function_that_can_fail()</function> are not
fatal to <function>my_function_that_can_fail()</function>:
<programlisting>
<informalexample><programlisting>
gboolean
my_function_that_can_fail (GError **err)
{
@ -226,7 +225,7 @@ my_function_that_can_fail (GError **err)
return FALSE;
}
}
</programlisting>
</programlisting></informalexample>
</para>
<para>

4
docs/reference/glib/tmpl/fileutils.sgml
View File

@ -17,9 +17,9 @@ various file-related functions.
<!-- ##### ENUM GFileError ##### -->
<para>
Values corresponding to <literal>errno</literal> codes returned from file operations
on UNIX. Unlike <literal>errno</literal> codes, #GFileError values are available on
on Unix. Unlike <literal>errno</literal> 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.

6
docs/reference/glib/tmpl/hash_tables.sgml
View File

@ -53,7 +53,7 @@ To destroy a #GHashTable use g_hash_table_destroy().
<!-- ##### STRUCT GHashTable ##### -->
<para>
The #GHashTable struct is an opaque data structure to represent a
The <structname>GHashTable</structname> struct is an opaque data structure to represent a
<link linkend="glib-Hash-Tables">Hash Table</link>.
It should only be accessed via the following functions.
</para>
@ -289,7 +289,7 @@ parameter, when using pointers as keys in a #GHashTable.
<para>
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.
</para>
@v: a gpointer key.
@ -313,7 +313,7 @@ parameter, when using pointers to integers as keys in a #GHashTable.
<para>
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.
</para>
@v: a pointer to a #gint key.

126
docs/reference/glib/tmpl/hooks.sgml
View File

@ -19,53 +19,18 @@ and the list of hook functions can be invoked.
<!-- ##### STRUCT GHookList ##### -->
<para>
<informaltable pgwide=1 frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>
<row>
<entry>#guint seq_id;</entry>
<entry>the next free #GHook id.</entry>
</row>
<row>
<entry>#guint hook_size;</entry>
<entry>the size of the #GHookList elements, in bytes.</entry>
</row>
<row>
<entry>#guint is_setup : 1;</entry>
<entry>1 if the #GHookList has been initialized.</entry>
</row>
<row>
<entry>#GHook *hooks;</entry>
<entry>the first #GHook element in the list.</entry>
</row>
<row>
<entry>#GMemChunk *hook_memchunk;</entry>
<entry>the #GMemChunk used for allocating the #GHook elements.</entry>
</row>
<row>
<entry>#GHookFinalizeFunc finalize_hook;</entry>
<entry>the function to call to finalize a #GHook element.
The default behaviour is to call the hooks <function>destroy</function>
function.</entry>
</row>
</tbody></tgroup></informaltable>
The <structname>GHookList</structname> struct represents a
list of hook functions.
</para>
@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 <function>destroy</function> function.
<!-- ##### USER_FUNCTION GHookFinalizeFunc ##### -->
<para>
@ -79,65 +44,22 @@ list of hooks gets finalized.
<!-- ##### STRUCT GHook ##### -->
<para>
<informaltable pgwide=1 frame="none" role="struct">
<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
<tbody>
<row>
<entry>#gpointer data;</entry>
<entry>data which is passed to func when this hook is invoked.</entry>
</row>
<row>
<entry>#GHook *next;</entry>
<entry>pointer to the next hook in the list.</entry>
</row>
<row>
<entry>#GHook *prev;</entry>
<entry>pointer to the previous hook in the list.</entry>
</row>
<row>
<entry>#guint ref_count;</entry>
<entry>the reference count of this hook.</entry>
</row>
<row>
<entry>#guint hook_id;</entry>
<entry>the id of this hook, which is unique within its list.</entry>
</row>
<row>
<entry>#guint flags;</entry>
<entry>flags which are set for this hook. See #GHookFlagMask for
predefined flags.</entry>
</row>
<row>
<entry>#gpointer func;</entry>
<entry>the function to call when this hook is invoked. The possible
signatures for this function are #GHookFunc and #GHookCheckFunc.</entry>
</row>
<row>
<entry>#GDestroyNotify destroy;</entry>
<entry>the default <function>finalize_hook</function> function of a
#GHookList calls this member of the hook that is being finalized.</entry>
</row>
</tbody></tgroup></informaltable>
The <structname>GHook</structname> struct represents a single hook
function in a #GHookList.
</para>
@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 <function>finalize_hook</function> function of a
#GHookList calls this member of the hook that is being finalized.
<!-- ##### USER_FUNCTION GHookFunc ##### -->
<para>

4
docs/reference/glib/tmpl/macros.sgml
View File

@ -53,8 +53,8 @@ BeOS-specific code in "#ifdef G_OS_BEOS".
<!-- ##### MACRO G_OS_UNIX ##### -->
<para>
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".
</para>

35
docs/reference/glib/tmpl/macros_misc.sgml
View File

@ -42,7 +42,8 @@ only one statement is expected by the compiler.
<!-- ##### MACRO G_BEGIN_DECLS ##### -->
<para>
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 <literal>extern "C"</literal>
around the header.
</para>
@ -92,16 +93,17 @@ Accepts a macro or a string and converts it into a string.
<!-- ##### MACRO G_GNUC_EXTENSION ##### -->
<para>
Expands to <literal>__extension__</literal> 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 <literal>-pedantic</literal> option.
Expands to <literal>__extension__</literal> when <command>gcc</command> is
used as the compiler.
This simply tells <command>gcc</command> not to warn about the following non-standard code
when compiling with the <option>-pedantic</option> option.
</para>
<!-- ##### MACRO G_GNUC_CONST ##### -->
<para>
Expands to the GNU C const function attribute if the compiler is GNU C.
Expands to the GNU C <literal>const</literal> function attribute if the compiler is <command>gcc</command>.
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.
<!-- ##### MACRO G_GNUC_NORETURN ##### -->
<para>
Expands to the GNU C noreturn function attribute if the compiler is GNU C.
Expands to the GNU C <literal>noreturn</literal> function attribute if the compiler is <command>gcc</command>.
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.
<!-- ##### MACRO G_GNUC_UNUSED ##### -->
<para>
Expands to the GNU C unused function attribute if the compiler is GNU C.
Expands to the GNU C <literal>unused</literal> function attribute if the compiler is <command>gcc</command>.
It is used for declaring functions which may never be used.
It avoids possible compiler warnings. See the GNU C documentation for details.
</para>
@ -137,7 +139,7 @@ It avoids possible compiler warnings. See the GNU C documentation for details.
<!-- ##### MACRO G_GNUC_PURE ##### -->
<para>
Expands to the GNU C pure function attribute if the compiler is GNU C.
Expands to the GNU C <literal>pure</literal> function attribute if the compiler is <command>gcc</command>.
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.
<!-- ##### MACRO G_GNUC_PRINTF ##### -->
<para>
Expands to the GNU C format function attribute if the compiler is GNU C.
Expands to the GNU C <literal>format</literal> function attribute if the compiler is <command>gcc</command>.
This is used for declaring functions which take a variable number of
arguments, with the same syntax as <function>printf()</function>.
It allows the compiler to type-check the arguments passed to the function.
@ -168,7 +170,7 @@ gint g_snprintf (gchar *string,
<!-- ##### MACRO G_GNUC_SCANF ##### -->
<para>
Expands to the GNU C format function attribute if the compiler is GNU C.
Expands to the GNU C <literal>format</literal> function attribute if the compiler is <command>gcc</command>.
This is used for declaring functions which take a variable number of
arguments, with the same syntax as <function>scanf()</function>.
It allows the compiler to type-check the arguments passed to the function.
@ -182,8 +184,8 @@ See the GNU C documentation for details.
<!-- ##### MACRO G_GNUC_FORMAT ##### -->
<para>
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 <literal>format_arg</literal> function attribute if the compiler is <command>gcc</command>.
This function attribute specifies that a function takes a format
string for a <function>printf()</function>, <function>scanf()</function>,
<function>strftime()</function> or <function>strfmon()</function> 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);
<!-- ##### MACRO G_GNUC_FUNCTION ##### -->
<para>
Expands to the GNU C <literal>__FUNCTION__</literal> variable if the
compiler is GNU C, or "" if it isn't. The GNU C
compiler is <command>gcc</command>, or "" if it isn't. The GNU C
<literal>__FUNCTION__</literal> variable contains the name of the
current function. See the GNU C documentation for details.
</para>
@ -213,7 +215,7 @@ current function. See the GNU C documentation for details.
<!-- ##### MACRO G_GNUC_PRETTY_FUNCTION ##### -->
<para>
Expands to the GNU C <literal>__PRETTY_FUNCTION__</literal> variable
if the compiler is GNU C, or "" if it isn't.
if the compiler is <command>gcc</command>, or "" if it isn't.
The GNU C <literal>__PRETTY_FUNCTION__</literal> variable contains the
name of the current function. For a C program this is the same as the
<literal>__FUNCTION__</literal> variable but for C++ it also includes
@ -225,8 +227,9 @@ GNU C documentation for details.
<!-- ##### MACRO G_GNUC_NO_INSTRUMENT ##### -->
<para>
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 <literal>no_instrument_function</literal> function
attribute if the compiler is <command>gcc</command>. Functions with this
attribute will not be
instrumented for profiling, when the compiler is called with the
<option>-finstrument-functions</option> option.
See the GNU C documentation for details.

8
docs/reference/glib/tmpl/main.sgml
View File

@ -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.
</para>
@ -593,7 +593,7 @@ g_main_context_set_poll_func() for full details.
<row>
<entry>#gint fd;</entry>
<entry>the file descriptor to poll (or a HANDLE on Win32 platforms).</entry>
<entry>the file descriptor to poll (or a <type>HANDLE</type> on Win32 platforms).</entry>
</row>
<row>
@ -640,9 +640,9 @@ event sources in a generic manner.
<entry>
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 <function>poll()</function> 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 <function>poll()</function> 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.
</entry>

5
docs/reference/glib/tmpl/markup.sgml
View File

@ -2,13 +2,12 @@
Simple XML Subset Parser
<!-- ##### SECTION Short_Description ##### -->
Parses a subset of XML
parses a subset of XML.
<!-- ##### SECTION Long_Description ##### -->
<para>
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

19
docs/reference/glib/tmpl/memory.sgml
View File

@ -124,12 +124,12 @@ If @mem is %NULL it simply returns.
<!-- ##### MACRO g_alloca ##### -->
<para>
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
<function>alloca()</function> function present on most Unix variants.
Thus it provides the same advantages and pitfalls as <function>alloca()</function>:
<msgtext><variablelist>
<varlistentry><term></term><listitem><para>
+ alloca() is very fast, as on most systems it's implemented by just adjusting
+ <function>alloca()</function> is very fast, as on most systems it's implemented by just adjusting
the stack pointer register.
</para></listitem></varlistentry>
<varlistentry><term></term><listitem><para>
@ -139,17 +139,17 @@ as alloca():
<varlistentry><term></term><listitem><para>
- 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 <funcion>alloca()</function> uses.
</para></listitem></varlistentry>
<varlistentry><term></term><listitem><para>
- 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 <function>malloc()</function>. 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.
</para></listitem></varlistentry>
<varlistentry><term></term><listitem><para>
- 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 <function>alloca()</function> with GNU C variable sized arrays.
Stack space allocated with <function>alloca()</function> 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.
</para></listitem></varlistentry>
@ -216,8 +216,7 @@ if it exists, should be prior to any use of GLib.
<!-- ##### FUNCTION g_mem_set_vtable ##### -->
<para>
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 <function>malloc()</function>, <function>realloc()</function>, and <function>free()</function>
custom memory allocation routines. <emphasis>This function must be called before using any other GLib functions.</emphasis> The @vtable only needs to provide <function>malloc()</function>, <function>realloc()</function>, and <function>free()</function>
functions; GLib can provide default implementations of the others. The <function>malloc()</function>
and <function>realloc()</function> implementations should return %NULL on failure, GLib will handle
error-checking for you. @vtable is copied, so need not persist after this

2
docs/reference/glib/tmpl/memory_chunks.sgml
View File

@ -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);

19
docs/reference/glib/tmpl/messages.sgml
View File

@ -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:
</para>
<informalexample><programlisting>
INCLUDES = \
-DG_LOG_DOMAIN=\"Gtk\"
INCLUDES = -DG_LOG_DOMAIN=\"Gtk\"
</programlisting></informalexample>
@ -112,7 +111,7 @@ documentation.
A convenience function/macro to log a normal message.
</para>
@...:
@...: the parameters to insert into the format string.
<!-- # Unused Parameters # -->
@format: the message format. See the <function>printf()</function>
documentation.
@ -124,7 +123,7 @@ documentation.
A convenience function/macro to log a warning message.
</para>
@...: 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 <function>printf()</function>)
<!-- ##### MACRO g_critical ##### -->
@ -136,7 +135,7 @@ warnings exit the program, then use g_critical() for fatal errors, for
example.
</para>
@...: 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 <function>printf()</function>)
<!-- ##### MACRO g_error ##### -->
@ -149,7 +148,7 @@ expect. Using this function indicates a bug in your program, i.e. an
assertion failure.
</para>
@...:
@...: the parameters to insert into the format string.
<!-- # Unused Parameters # -->
@format: the message format. See the <function>printf()</function>
documentation.
@ -160,11 +159,11 @@ documentation.
<para>
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.
</para>
<para>
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.
</para>
<para>
@ -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.

11
docs/reference/glib/tmpl/misc_utils.sgml
View File

@ -53,7 +53,7 @@ Gets the user name of the current user.
<!-- ##### FUNCTION g_get_real_name ##### -->
<para>
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
<filename>passwd</filename> file.
</para>
@ -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 <envar>TMPDIR</envar>,
<envar>TMP</envar>, and <envar>TEMP</envar>
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.
</para>
@Returns: the directory to use for temporary files.
@ -123,7 +124,7 @@ The returned string should be freed when no longer needed.
<para>
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.
</para>
@file_name: a file name.
@ -133,7 +134,7 @@ or 'C:/windows' on windows systems.
<!-- ##### FUNCTION g_path_skip_root ##### -->
<para>
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.
</para>
@ -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.
</para>
@num: a guint.
@num: a #guint.
@Returns: the smallest prime number from a built-in array of primes which is
larger than @num.

2
docs/reference/glib/tmpl/modules.sgml
View File

@ -199,7 +199,7 @@ It is passed the #GModule structure.
<para>
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".
</para>

9
docs/reference/glib/tmpl/numerical.sgml
View File

@ -2,8 +2,7 @@
Numerical Definitions
<!-- ##### SECTION Short_Description ##### -->
Mathematical constants, and floating point decomposition.
mathematical constants, and floating point decomposition.
<!-- ##### SECTION Long_Description ##### -->
<para>
@ -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: <ulink url="http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html">http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html</ulink>
storage) by at least Intel, PPC and Sparc, for reference: <ulink url="http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html">http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html</ulink>
</para>
<!-- ##### SECTION See_Also ##### -->
@ -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:
<ulink url="http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html">http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html</ulink>
</para>
@ -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:
<ulink url="http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html">http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html</ulink>
</para>

3
docs/reference/glib/tmpl/patterns.sgml
View File

@ -2,8 +2,7 @@
Glob-style pattern matching
<!-- ##### SECTION Short_Description ##### -->
Matches strings against patterns containing '*' (wildcard) and '?' (joker).
matches strings against patterns containing '*' (wildcard) and '?' (joker).
<!-- ##### SECTION Long_Description ##### -->
<para>

2
docs/reference/glib/tmpl/queue.sgml
View File

@ -2,7 +2,7 @@
Double-ended Queues
<!-- ##### SECTION Short_Description ##### -->
double-ended queue data structure
double-ended queue data structure.
<!-- ##### SECTION Long_Description ##### -->
<para>

2
docs/reference/glib/tmpl/shell.sgml
View File

@ -2,7 +2,7 @@
Shell-related Utilities
<!-- ##### SECTION Short_Description ##### -->
shell-like commandline handling
shell-like commandline handling.
<!-- ##### SECTION Long_Description ##### -->
<para>

2
docs/reference/glib/tmpl/spawn.sgml
View File

@ -2,7 +2,7 @@
Spawning Processes
<!-- ##### SECTION Short_Description ##### -->
Process launching with <function>fork()</function>/<function>exec()</function>
process launching with <function>fork()</function>/<function>exec()</function>.
<!-- ##### SECTION Long_Description ##### -->
<para>

134
docs/reference/glib/tmpl/string_utils.sgml
View File

@ -122,11 +122,10 @@ an even better idea.
<!-- ##### FUNCTION g_strlcat ##### -->
<para>
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 <function>strlcat()</function> 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 <function>strcat()</function> or
<function>strncat()</function>, but for real security g_strconcat() is harder to mess up.
</para>
@dest: destination buffer, already containing one nul-terminated string
@ -230,12 +229,12 @@ documentation.
Determines whether a character is alphanumeric.
</para>
<para>
Unlike the standard C library isalnum function, this only
Unlike the standard C library <function>isalnum()</function> 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 <type>char</type>, not an <type>int</type>,
so don't call it on %EOF but no need to cast to #guchar before passing a
possibly non-ASCII character in.
</para>
@c: any character
@ -247,12 +246,12 @@ non-ASCII character in.
Determines whether a character is alphabetic (i.e. a letter).
</para>
<para>
Unlike the standard C library isalpha function, this only
Unlike the standard C library <function>isalpha()</function> 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 <type>char</type>, not an <type>int</type,
so don't call it on %EOF but no need to cast to #guchar before passing a
possibly non-ASCII character in.
</para>
@c: any character
@ -264,12 +263,12 @@ non-ASCII character in.
Determines whether a character is a control character.
</para>
<para>
Unlike the standard C library iscntrl function, this only
Unlike the standard C library <function>iscntrl()</function> 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 <type>char</type>, not an <type>int</type>,
so don't call it on %EOF but no need to cast to #guchar before passing a
possibly non-ASCII character in.
</para>
@c: any character
@ -281,9 +280,9 @@ non-ASCII character in.
Determines whether a character is digit (0-9).
</para>
<para>
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 <function>isdigit()</function> function,
this takes a <type>char</type>, not an <type>int</type>, so don't call it
on %EOF but no need to cast to #guchar before passing a possibly
non-ASCII character in.
</para>
@ -296,12 +295,12 @@ non-ASCII character in.
Determines whether a character is a printing character and not a space.
</para>
<para>
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 <function>isgraph()</function> 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 <type>char</type>, not an <type>int</type>,
so don't call it on %EOF but no need to cast to #guchar before passing a
possibly non-ASCII character in.
</para>
@c: any character
@ -313,12 +312,12 @@ non-ASCII character in.
Determines whether a character is an ASCII lower case letter.
</para>
<para>
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 <function>islower()</function> 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 <type>char</type>, not an <type>int</type>,
so don't call it on %EOF but no need to worry about casting to #guchar
before passing a possibly non-ASCII character in.
</para>
@c: any character
@ -330,12 +329,12 @@ a possibly non-ASCII character in.
Determines whether a character is a printing character.
</para>
<para>
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 <function>isprint()</function> 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 <type>char</type>, not an <type>int</type>,
so don't call it on %EOF but no need to cast to #guchar before passing a
possibly non-ASCII character in.
</para>
@c: any character
@ -347,12 +346,12 @@ non-ASCII character in.
Determines whether a character is a punctuation character.
</para>
<para>
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 <function>ispunct()</function> 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 <type>char</type>, not an <type>int</type>,
so don't call it on %EOF but no need to cast to #guchar before passing a
possibly non-ASCII character in.
</para>
@c: any character
@ -364,12 +363,12 @@ non-ASCII character in.
Determines whether a character is a white-space character.
</para>
<para>
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 <function>isspace()</function> 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 <type>char</type>, not an <type>int</type>,
so don't call it on %EOF but no need to cast to #guchar before passing a
possibly non-ASCII character in.
</para>
@c: any character
@ -381,12 +380,12 @@ non-ASCII character in.
Determines whether a character is an ASCII upper case letter.
</para>
<para>
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 <function>isupper()</function> 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 <type>char</type>, not an <type>int</type>,
so don't call it on %EOF but no need to worry about casting to #guchar
before passing a possibly non-ASCII character in.
</para>
@c: any character
@ -398,9 +397,9 @@ a possibly non-ASCII character in.
Determines whether a character is a hexadecimal-digit character.
</para>
<para>
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 <function>isxdigit()</function> function,
this takes a <type>char</type>, not an <type>int</type>, so
don't call it on %EOF but no need to cast to #guchar before passing a
possibly non-ASCII character in.
</para>
@ -554,7 +553,8 @@ of the strings.
</para>
<para>
The problem with g_strncasecmp() is that it does the comparison by
calling toupper()/tolower() on each byte. toupper()/tolower() are
calling <function>toupper()</function>/<function>tolower()</function>
on each byte. <function>toupper()</function>/<function>tolower()</function> 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.
<!-- ##### FUNCTION g_strreverse ##### -->
<para>
Reverses all of the characters in a string.
For example, g_strreverse ("abcdef") will result in "fedcba".
For example, <literal>g_strreverse ("abcdef")</literal> will result in "fedcba".
</para>
@string: the string to reverse.
@ -589,19 +589,17 @@ For example, g_strreverse ("abcdef") will result in "fedcba".
<!-- ##### MACRO G_ASCII_DTOSTR_BUF_SIZE ##### -->
<para>
A good size for a buffer to be passed into <function>g_ascii_dtostr</function>.
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.
</para>
<para>
The typical usage would be something like:
</para>
<para>
<literal>
<informalexample><programlisting>
char buf[G_ASCII_DTOSTR_BUF_SIZE];
fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value));
</literal>
</programlisting></informalexample>
</para>
@ -694,7 +692,7 @@ standard delimiters defined in #G_STR_DELIMITERS.
<!-- ##### MACRO G_STR_DELIMITERS ##### -->
<para>
The standard delimiters, used in #g_strdelimit.
The standard delimiters, used in g_strdelimit().
</para>

2
docs/reference/glib/tmpl/thread_pools.sgml
View File

@ -2,7 +2,7 @@
Thread Pools
<!-- ##### SECTION Short_Description ##### -->
Pools of threads to execute work concurrently
pools of threads to execute work concurrently.
<!-- ##### SECTION Long_Description ##### -->
<para>

35
docs/reference/glib/tmpl/threads.sgml
View File

@ -158,7 +158,7 @@ really know what you are doing.
<note>
<para>
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().
</para>
</note>
@ -172,7 +172,7 @@ system is initialized, you can do that too:
<para>
<informalexample>
<programlisting>
if (!g_thread_supported ()) g_thread_init (NULL);
if (!g_thread_supported (<!>)) g_thread_init (NULL);
</programlisting>
</informalexample>
</para>
@ -362,7 +362,7 @@ This functions returns the #GThread corresponding to the calling thread.
<!-- ##### FUNCTION g_thread_join ##### -->
<para>
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.
<!-- ##### FUNCTION g_thread_set_priority ##### -->
<para>
Change the priority of @thread to @priority.
Changes the priority of @thread to @priority.
</para>
<note>
@ -394,7 +394,7 @@ being dependent on priorities.
<!-- ##### FUNCTION g_thread_yield ##### -->
<para>
Give way to other threads waiting to be scheduled.
Gives way to other threads waiting to be scheduled.
</para>
<para>
@ -407,7 +407,7 @@ to do that. So in general you shouldn't use that function.
<!-- ##### FUNCTION g_thread_exit ##### -->
<para>
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().
<note>
<para>
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.
</para>
</note>
@ -459,7 +458,7 @@ access. Take for example the following function:
<example>
<title>A function which will not work in a threaded environment</title>
<programlisting>
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:
<example>
<title>The wrong way to write a thread-safe function</title>
<programlisting>
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 <function>give_me_next_number()</function> example:
</para>
<para>
<example>
<title>Using GStaticMutex to simplify thread-safe programming</title>
<title>Using <structname>GStaticMutex</structname> to simplify thread-safe programming</title>
<programlisting>
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
<para>
<example>
<title>Using the G_LOCK_* convenience macros</title>
<title>Using the %G_LOCK_* convenience macros</title>
<programlisting>
G_LOCK_DEFINE (current_number);
int give_me_next_number ()
int give_me_next_number (<!>)
{
static int current_number = 0;
int ret_val;

2
docs/reference/glib/tmpl/timers.sgml
View File

@ -3,7 +3,7 @@ Timers
<!-- ##### SECTION Short_Description ##### -->
Keep track of elapsed time.
keep track of elapsed time.
<!-- ##### SECTION Long_Description ##### -->
<para>

6
docs/reference/glib/tmpl/trees-binary.sgml
View File

@ -2,13 +2,13 @@
Balanced Binary Trees
<!-- ##### SECTION Short_Description ##### -->
a sorted collection of key/value pairs optimised for searching
a sorted collection of key/value pairs optimized for searching
and traversing in order.
<!-- ##### SECTION Long_Description ##### -->
<para>
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.
</para>
<para>
To create a new #GTree use g_tree_new().
@ -42,7 +42,7 @@ To destroy a #GTree, use g_tree_destroy().
<!-- ##### STRUCT GTree ##### -->
<para>
The #GTree struct is an opaque data structure representing a
The <structname>GTree</structname> struct is an opaque data structure representing a
<link linkend="glib-Balanced-Binary-Trees">Balanced Binary Tree</link>.
It should be accessed only by using the following functions.
</para>

10
docs/reference/glib/tmpl/trees-nary.sgml
View File

@ -51,16 +51,16 @@ g_node_destroy().
<!-- ##### STRUCT GNode ##### -->
<para>
The #GNode struct represents one node in a
The <structname>GNode</structname> struct represents one node in a
<link linkend="glib-N-ary-Trees">N-ary Tree</link>.
The <structfield>data</structfield> field contains the actual data of the node.
The <structfield>next</structfield> and <structfield>prev</structfield>
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 <structname>GNode</structname> with the
same parent).
The <structfield>parent</structfield> field points to the parent of the #GNode,
or is %NULL if the #GNode is the root of the tree.
The <structfield>parent</structfield> field points to the parent of the <structname>GNode</structname>,
or is %NULL if the <structname>GNode</structname> is the root of the tree.
The <structfield>children</structfield> field points to the first child of the
#GNode. The other children are accessed by using the
<structname>GNode</structname>. The other children are accessed by using the
<structfield>next</structfield> pointer of each child.
</para>

14
docs/reference/glib/tmpl/type_conversion.sgml
View File

@ -3,7 +3,7 @@ Type Conversion Macros
<!-- ##### SECTION Short_Description ##### -->
Portably storing integers in pointer variables.
portably storing integers in pointer variables.
<!-- ##### SECTION Long_Description ##### -->
<para>
@ -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:
<programlisting>
<informalexample><programlisting>
int *ip = g_new (int, 1);
*ip = 42;
</programlisting>
</programlisting></informalexample>
But this is inconvenient, and it's annoying to have to free the
memory at some later time.
</para>
@ -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:
<programlisting>
<informalexample><programlisting>
gpointer p;
int i;
p = (void*) 42;
i = (int) p;
</programlisting>
</programlisting></informalexample>
Again, that example was <emphasis>not</emphasis> correct, don't copy it.
The problem is that on some systems you need to do this:
<programlisting>
<informalexample><programlisting>
gpointer p;
int i;
p = (void*) (long) 42;
i = (int) (long) p;
</programlisting>
</programlisting></informalexample>
So GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. do the right thing
on the current platform.
</para>

6
docs/reference/glib/tmpl/unicode.sgml
View File

@ -31,7 +31,7 @@ Convenience functions for converting between UTF-8 and the locale encoding.
<!-- ##### TYPEDEF gunichar ##### -->
<para>
A type which can hold any UCS-4 character code.
A type which can hold any UCS-4 character code.
</para>
@ -346,7 +346,7 @@ See <ulink url="http://www.unicode.org/unicode/reports/tr14/"
<!-- ##### MACRO g_utf8_next_char ##### -->
<para>
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.
<!-- ##### ENUM GNormalizeMode ##### -->
<para>
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.

8
docs/reference/glib/tmpl/warnings.sgml
View File

@ -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.
</para>
@ -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.
</para>
@ -172,7 +172,7 @@ The prompt is then shown again.
If [P]roceed is selected, the function returns.
</para>
<para>
This function may cause different actions on non-unix platforms.
This function may cause different actions on non-Unix platforms.
</para>
@prg_name: the program name, needed by <command>gdb</command> for the [S]tack trace option.
@ -186,7 +186,7 @@ Invokes <command>gdb</command>, which attaches to the current process and shows
Called by g_on_error_query() when the [S]tack trace option is selected.
</para>
<para>
This function may cause different actions on non-unix platforms.
This function may cause different actions on non-Unix platforms.
</para>
@prg_name: the program name, needed by <command>gdb</command> for the [S]tack trace option.

14
docs/reference/glib/tmpl/windows.sgml
View File

@ -2,7 +2,7 @@
Windows Compatibility Functions
<!-- ##### SECTION Short_Description ##### -->
Unix emulation on Windows
Unix emulation on Windows.
<!-- ##### SECTION Long_Description ##### -->
<para>
@ -16,7 +16,7 @@ Unix emulation on Windows
<!-- ##### MACRO MAXPATHLEN ##### -->
<para>
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).
</para>
@ -25,14 +25,14 @@ macro %MAXPATHLEN, which is the maximum length of a filename
<!-- ##### TYPEDEF pid_t ##### -->
<para>
Provided for UNIX emulation on Windows; process ID type.
Provided for Unix emulation on Windows; process ID type.
</para>
<!-- ##### MACRO pipe ##### -->
<para>
Provided for UNIX emulation on Windows; see documentation for <function>pipe()</function>
in any UNIX manual.
Provided for Unix emulation on Windows; see documentation for <function>pipe()</function>
in any Unix manual.
</para>
@phandles:
@ -40,8 +40,8 @@ in any UNIX manual.
<!-- ##### MACRO ftruncate ##### -->
<para>
Provided for UNIX emulation on Windows; see documentation for <function>ftruncate()</function>
in any UNIX manual.
Provided for Unix emulation on Windows; see documentation for <function>ftruncate()</function>
in any Unix manual.
</para>
@fd:

60
glib/gconvert.c
View File

@ -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 <function>iconv_open()</function>, 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 <function>iconv()</function>, 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 <function>iconv_close()</function>, 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 <function>iconv()</function> 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 *

6
glib/ghash.c
View File

@ -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,

22
glib/grand.c
View File

@ -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 <filename>/dev/urandom</filename> (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 <function>g_random_*</function> functions, to @seed.
**/
void
g_random_set_seed (guint32 seed)

24
glib/gthreadpool.c
View File

@ -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.
*

14
glib/gtree.c
View File

@ -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