Commit 3fa33317 authored by Matthias Clasen's avatar Matthias Clasen

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.
parent 24608fc1
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):
......
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):
......
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):
......
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):
......
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):
......
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):
......
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):
......
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):
......
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
......
......@@ -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>
......
......@@ -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;
......
......@@ -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.
......
......@@ -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>
......
......@@ -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>
......
......@@ -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,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>
......
......@@ -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>
......
......@@ -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>
......
......@@ -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>
......
......@@ -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.
......
......@@ -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.
......
......@@ -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>
The <structname>GHook</structname> struct represents a single hook
function in a #GHookList.
</para>
@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.
<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>
</para>
@data:
@next:
@prev:
@ref_count:
@hook_id:
@flags:
@func:
@destroy:
<!-- ##### USER_FUNCTION GHookFunc ##### -->
<para>
......
......@@ -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>
......
......@@ -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.