Update.

        * glib/tmpl/hooks.sgml, glib/tmpl/spawn.sgml,
        glib/tmpl/macros_misc.sgml: Update.

        * glib/tmpl/linked_lists_double.sgml, glib/tmpl/trees-binary.sgml,
        glib/glib-sections.txt: Document GCompareDataFunc.

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 5cc1201..a48955c 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,11 @@
+2001-10-05  Matthias Clasen  <matthiasc@poet.de>
+
+       * glib/tmpl/hooks.sgml, glib/tmpl/spawn.sgml,
+       glib/tmpl/macros_misc.sgml: Update. 
+
+       * glib/tmpl/linked_lists_double.sgml, glib/tmpl/trees-binary.sgml,
+       glib/glib-sections.txt: Document GCompareDataFunc.
+
 2001-10-02  Matthias Clasen  <matthiasc@poet.de>
 
        * glib/tmpl/iochannel.sgml, glib/tmpl/macros_misc.sgml,

diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt
index c20843f..5968f5a 100644 (file)
--- a/docs/reference/glib/glib-sections.txt
+++ b/docs/reference/glib/glib-sections.txt
@@ -1048,19 +1048,19 @@ g_date_sunday_weeks_in_year
 <TITLE>Hook Functions</TITLE>
 <FILE>hooks</FILE>
 GHookList
+GHookFinalizeFunc
 GHook
 GHookFunc
 GHookCheckFunc
-GHookMarshaller
-GHookCheckMarshaller
-GHookFinalizeFunc
 
 <SUBSECTION>
 g_hook_list_init
 g_hook_list_invoke
 g_hook_list_invoke_check
 g_hook_list_marshal
+GHookMarshaller
 g_hook_list_marshal_check
+GHookCheckMarshaller
 g_hook_list_clear
 
 <SUBSECTION>
@@ -1075,9 +1075,9 @@ g_hook_compare_ids
 <SUBSECTION>
 g_hook_get
 g_hook_find
+GHookFindFunc
 g_hook_find_data
 g_hook_find_func
-GHookFindFunc
 g_hook_find_func_data
 
 <SUBSECTION>
@@ -1341,8 +1341,9 @@ g_list_length
 g_list_copy
 g_list_reverse
 g_list_sort
-g_list_sort_with_data
 GCompareFunc
+g_list_sort_with_data
+GCompareDataFunc
 g_list_concat
 g_list_foreach
 GFunc
@@ -1591,7 +1592,6 @@ GTree
 g_tree_new
 g_tree_new_with_data
 g_tree_new_full
-GCompareDataFunc
 g_tree_insert
 g_tree_replace
 g_tree_nnodes

diff --git a/docs/reference/glib/tmpl/hooks.sgml b/docs/reference/glib/tmpl/hooks.sgml
index 6ac4c43..7762b33 100644 (file)
--- a/docs/reference/glib/tmpl/hooks.sgml
+++ b/docs/reference/glib/tmpl/hooks.sgml
@@ -50,13 +50,10 @@ and the list of hook functions can be invoked.
 </row>
 
 <row>
-<entry>#GHookFreeFunc hook_free;</entry>
-<entry>the function to call to free a #GHook element.</entry>
-</row>
-
-<row>
-<entry>#GHookFreeFunc hook_destroy;</entry>
-<entry>the function to call to destory a #GHook element.</entry>
+<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>
@@ -70,6 +67,17 @@ and the list of hook functions can be invoked.
 @hook_memchunk: 
 @finalize_hook: 
 
+
+<!-- ##### USER_FUNCTION GHookFinalizeFunc ##### -->
+<para>
+Defines the type of function to be called when a hook in a 
+list of hooks gets finalized.
+</para>
+
+@hook_list: a #GHookList.
+@hook: the hook in @hook_list that gets finalized.
+
+
 <!-- ##### STRUCT GHook ##### -->
 <para>
 
@@ -79,42 +87,45 @@ and the list of hook functions can be invoked.
 
 <row>
 <entry>#gpointer data;</entry>
-<entry>.</entry>
+<entry>data which is passed to func when this hook is invoked.</entry>
 </row>
 
 <row>
 <entry>#GHook *next;</entry>
-<entry>.</entry>
+<entry>pointer to the next hook in the list.</entry>
 </row>
 
 <row>
 <entry>#GHook *prev;</entry>
-<entry>.</entry>
+<entry>pointer to the previous hook in the list.</entry>
 </row>
 
 <row>
 <entry>#guint ref_count;</entry>
-<entry>.</entry>
+<entry>the reference count of this hook.</entry>
 </row>
 
 <row>
 <entry>#guint hook_id;</entry>
-<entry>.</entry>
+<entry>the id of this hook, which is unique within its list.</entry>
 </row>
 
 <row>
 <entry>#guint flags;</entry>
-<entry>.</entry>
+<entry>flags which are set for this hook. See #GHookFlagMask for
+predefined flags.</entry>
 </row>
 
 <row>
-<entry>#gpointer data;</entry>
-<entry>.</entry>
+<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>.</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>
@@ -131,51 +142,21 @@ and the list of hook functions can be invoked.
 
 <!-- ##### USER_FUNCTION GHookFunc ##### -->
 <para>
-
+Defines the type of a hook function that can be invoked
+by g_hook_list_invoke().
 </para>
 
-@data: 
+@data: the data field of the #GHook is passed to the hook function here.
 
 
 <!-- ##### USER_FUNCTION GHookCheckFunc ##### -->
 <para>
-
-</para>
-
-@data: 
-@Returns: 
-
-
-<!-- ##### USER_FUNCTION GHookMarshaller ##### -->
-<para>
-
-</para>
-
-@hook: 
-@marshal_data: 
-<!-- # Unused Parameters # -->
-@data: 
-
-
-<!-- ##### USER_FUNCTION GHookCheckMarshaller ##### -->
-<para>
-
-</para>
-
-@hook: 
-@marshal_data: 
-@Returns: 
-<!-- # Unused Parameters # -->
-@data: 
-
-
-<!-- ##### USER_FUNCTION GHookFinalizeFunc ##### -->
-<para>
-
+Defines the type of a hook function that can be invoked
+by g_hook_list_invoke_check().
 </para>
 
-@hook_list: 
-@hook: 
+@data: the data field of the #GHook is passed to the hook function here.
+@Returns: %FALSE if the #GHook should be destroyed. 
 
 
 <!-- ##### FUNCTION g_hook_list_init ##### -->
@@ -186,7 +167,7 @@ This must be called before the #GHookList is used.
 
 @hook_list: a #GHookList.
 @hook_size: the size of each element in the #GHookList, typically
-sizeof (GHook).
+<literal>sizeof (GHook)</literal>.
 
 
 <!-- ##### FUNCTION g_hook_list_invoke ##### -->
@@ -195,45 +176,63 @@ Calls all of the #GHook functions in a #GHookList.
 </para>
 
 @hook_list: a #GHookList.
-@may_recurse: TRUE if functions which are already running (e.g. in another
-thread) can be called. If set to FALSE, these are skipped.
+@may_recurse: %TRUE if functions which are already running (e.g. in another
+thread) can be called. If set to %FALSE, these are skipped.
 
 
 <!-- ##### FUNCTION g_hook_list_invoke_check ##### -->
 <para>
 Calls all of the #GHook functions in a #GHookList.
-Any function which returns TRUE is removed from the #GHookList.
+Any function which returns %TRUE is removed from the #GHookList.
 </para>
 
 @hook_list: a #GHookList.
-@may_recurse: TRUE if functions which are already running (e.g. in another
-thread) can be called. If set to FALSE, these are skipped.
+@may_recurse: %TRUE if functions which are already running (e.g. in another
+thread) can be called. If set to %FALSE, these are skipped.
 
 
 <!-- ##### FUNCTION g_hook_list_marshal ##### -->
 <para>
-
+Calls a function on each valid #GHook. 
 </para>
 
 @hook_list: a #GHookList.
-@may_recurse: 
-@marshaller: 
-@marshal_data: 
-<!-- # Unused Parameters # -->
-@data: 
+@may_recurse: %TRUE if hooks which are currently running (e.g. in another
+thread) are considered valid. If set to %FALSE, these are skipped.
+@marshaller: the function to call for each #GHook.
+@marshal_data: data to pass to @marshaller.
 
 
-<!-- ##### FUNCTION g_hook_list_marshal_check ##### -->
+<!-- ##### USER_FUNCTION GHookMarshaller ##### -->
 <para>
+Defines the type of function used by g_hook_list_marshal().
+</para>
 
+@hook: a #GHook.
+@marshal_data: user data.
+
+
+<!-- ##### FUNCTION g_hook_list_marshal_check ##### -->
+<para>
+Calls a function on each valid #GHook and destroys it if the 
+function returns %FALSE.
 </para>
 
 @hook_list: a #GHookList.
-@may_recurse: 
-@marshaller: 
-@marshal_data: 
-<!-- # Unused Parameters # -->
-@data: 
+@may_recurse: %TRUE if hooks which are currently running (e.g. in another
+thread) are considered valid. If set to %FALSE, these are skipped.
+@marshaller: the function to call for each #GHook.
+@marshal_data: data to pass to @marshaller.
+
+
+<!-- ##### USER_FUNCTION GHookCheckMarshaller ##### -->
+<para>
+Defines the type of function used by g_hook_list_marshal_check().
+</para>
+
+@hook: a #GHook.
+@marshal_data: user data.
+@Returns: %FALSE if @hook should be destroyed.
 
 
 <!-- ##### FUNCTION g_hook_list_clear ##### -->
@@ -315,12 +314,12 @@ if the second id is greater than the first.
 
 <!-- ##### FUNCTION g_hook_get ##### -->
 <para>
-Returns the #GHook with the given id, or NULL if it is not found.
+Returns the #GHook with the given id, or %NULL if it is not found.
 </para>
 
 @hook_list: a #GHookList.
 @hook_id: a hook id.
-@Returns: the #GHook with the given id, or NULL if it is not found.
+@Returns: the #GHook with the given id, or %NULL if it is not found.
 
 
 <!-- ##### FUNCTION g_hook_find ##### -->
@@ -329,12 +328,22 @@ Finds a #GHook in a #GHookList using the given function to test for a match.
 </para>
 
 @hook_list: a #GHookList.
-@need_valids: TRUE if #GHook elements which have been destroyed should be
+@need_valids: %TRUE if #GHook elements which have been destroyed should be
 skipped.
-@func: the function to call for each #GHook, which should return TRUE when
+@func: the function to call for each #GHook, which should return %TRUE when
 the #GHook has been found.
-@data: the data passed to @func.
-@Returns: the found #GHook or NULL if no matching #GHook is found.
+@data: the data to pass to @func.
+@Returns: the found #GHook or %NULL if no matching #GHook is found.
+
+
+<!-- ##### USER_FUNCTION GHookFindFunc ##### -->
+<para>
+Defines the type of the function passed to g_hook_find().
+</para>
+
+@hook: a #GHook.
+@data: user data passed to g_hook_find_func().
+@Returns: %TRUE if the required #GHook has been found.
 
 
 <!-- ##### FUNCTION g_hook_find_data ##### -->
@@ -343,10 +352,10 @@ Finds a #GHook in a #GHookList with the given data.
 </para>
 
 @hook_list: a #GHookList.
-@need_valids: TRUE if #GHook elements which have been destroyed should be
+@need_valids: %TRUE if #GHook elements which have been destroyed should be
 skipped.
 @data: the data to find.
-@Returns: the #GHook with the given @data or NULL if no matching
+@Returns: the #GHook with the given @data or %NULL if no matching
 #GHook is found.
 
 
@@ -356,34 +365,24 @@ Finds a #GHook in a #GHookList with the given function.
 </para>
 
 @hook_list: a #GHookList.
-@need_valids: TRUE if #GHook elements which have been destroyed should be
+@need_valids: %TRUE if #GHook elements which have been destroyed should be
 skipped.
 @func: the function to find.
-@Returns: the #GHook with the given @func or NULL if no matching
+@Returns: the #GHook with the given @func or %NULL if no matching
 #GHook is found.
 
 
-<!-- ##### USER_FUNCTION GHookFindFunc ##### -->
-<para>
-Defines the type of the function passed to g_hooK_find_func().
-</para>
-
-@hook: a #GHook.
-@data: user data passed to g_hook_find_func().
-@Returns: TRUE if the required #GHook has been found.
-
-
 <!-- ##### FUNCTION g_hook_find_func_data ##### -->
 <para>
 Finds a #GHook in a #GHookList with the given function and data.
 </para>
 
 @hook_list: a #GHookList.
-@need_valids: TRUE if #GHook elements which have been destroyed should be
+@need_valids: %TRUE if #GHook elements which have been destroyed should be
 skipped.
 @func: the function to find.
 @data: the data to find.
-@Returns: the #GHook with the given @func and @data or NULL if no matching
+@Returns: the #GHook with the given @func and @data or %NULL if no matching
 #GHook is found.
 
 
@@ -396,9 +395,9 @@ g_hook_next_valid() if you are stepping through the #GHookList.)
 </para>
 
 @hook_list: a #GHookList.
-@may_be_in_call: TRUE if hooks which are currently running (e.g. in another
-thread) are considered valid. If set to FALSE, these are skipped.
-@Returns: the first valid #GHook, or NULL if none are valid.
+@may_be_in_call: %TRUE if hooks which are currently running (e.g. in another
+thread) are considered valid. If set to %FALSE, these are skipped.
+@Returns: the first valid #GHook, or %NULL if none are valid.
 
 
 <!-- ##### FUNCTION g_hook_next_valid ##### -->
@@ -406,32 +405,32 @@ thread) are considered valid. If set to FALSE, these are skipped.
 Returns the next #GHook in a #GHookList which has not been destroyed.
 The reference count for the #GHook is incremented, so you must call
 g_hook_unref() to restore it when no longer needed. (Or continue to call
-g_hook_next_valid() until NULL is returned.)
+g_hook_next_valid() until %NULL is returned.)
 
 </para>
 
 @hook_list: a #GHookList.
 @hook: the current #GHook.
-@may_be_in_call: TRUE if hooks which are currently running (e.g. in another
-thread) are considered valid. If set to FALSE, these are skipped.
-@Returns: the next valid #GHook, or NULL if none are valid.
+@may_be_in_call: %TRUE if hooks which are currently running (e.g. in another
+thread) are considered valid. If set to %FALSE, these are skipped.
+@Returns: the next valid #GHook, or %NULL if none are valid.
 
 
 <!-- ##### ENUM GHookFlagMask ##### -->
 <para>
-
+Flags used internally in the #GHook implementation.
 </para>
 
-@G_HOOK_FLAG_ACTIVE: 
-@G_HOOK_FLAG_IN_CALL: 
+@G_HOOK_FLAG_ACTIVE: set if the hook has not been destroyed. 
+@G_HOOK_FLAG_IN_CALL: set if the hook is currently being run. 
 @G_HOOK_FLAG_MASK: 
 
 <!-- ##### MACRO G_HOOK_FLAGS ##### -->
 <para>
-
+Returns the flags of a hook.
 </para>
 
-@hook: 
+@hook: a #GHook.
 
 
 <!-- ##### MACRO G_HOOK_FLAG_USER_SHIFT ##### -->
@@ -443,49 +442,49 @@ thread) are considered valid. If set to FALSE, these are skipped.
 
 <!-- ##### MACRO G_HOOK ##### -->
 <para>
-
+Casts a pointer to a <literal>GHook*</literal>.
 </para>
 
-@hook: 
+@hook: a pointer.
 
 
 <!-- ##### MACRO G_HOOK_IS_VALID ##### -->
 <para>
-Returns TRUE if the #GHook is valid, i.e. it is in a #GHookList, it is active
+Returns %TRUE if the #GHook is valid, i.e. it is in a #GHookList, it is active
 and it has not been destroyed.
 </para>
 
 @hook: a #GHook.
-@Returns: TRUE if the #GHook is valid.
+@Returns: %TRUE if the #GHook is valid.
 
 
 <!-- ##### MACRO G_HOOK_ACTIVE ##### -->
 <para>
-Returns TRUE if the #GHook is active, which is normally TRUE until the #GHook
+Returns %TRUE if the #GHook is active, which is normally %TRUE until the #GHook
 is destroyed.
 </para>
 
 @hook: a #GHook.
-@Returns: TRUE if the #GHook is active.
+@Returns: %TRUE if the #GHook is active.
 
 
 <!-- ##### MACRO G_HOOK_IN_CALL ##### -->
 <para>
-Returns TRUE if the #GHook function is currently executing.
+Returns %TRUE if the #GHook function is currently executing.
 </para>
 
 @hook: a #GHook.
-@Returns: TRUE if the #GHook function is currently executing.
+@Returns: %TRUE if the #GHook function is currently executing.
 
 
 <!-- ##### MACRO G_HOOK_IS_UNLINKED ##### -->
 <para>
-Returns TRUE if the #GHook is not in a #GHookList.
+Returns %TRUE if the #GHook is not in a #GHookList.
 
 </para>
 
 @hook: a #GHook.
-@Returns: TRUE if the #GHook is not in a #GHookList.
+@Returns: %TRUE if the #GHook is not in a #GHookList.
 
 
 <!-- ##### FUNCTION g_hook_ref ##### -->
@@ -505,7 +504,7 @@ and g_hook_free() is called to free it.
 </para>
 
 @hook_list: a #GHookList.
-@hook: 
+@hook: the #GHook to unref.
 
 
 <!-- ##### FUNCTION g_hook_free ##### -->
@@ -525,13 +524,13 @@ Destroys a #GHook, given its ID.
 
 @hook_list: a #GHookList.
 @hook_id: a hook ID.
-@Returns: TRUE if the #GHook was found in the #GHookList and destroyed.
+@Returns: %TRUE if the #GHook was found in the #GHookList and destroyed.
 
 
 <!-- ##### FUNCTION g_hook_destroy_link ##### -->
 <para>
-Removes one #GHook from a #GHookList, calling the @hook_destroy function in
-the #GHookList, and the @destroy function of the #GHook, if they exist.
+Removes one #GHook from a #GHookList, marking it inactive and calling
+g_hook_unref() on it. 
 </para>
 
 @hook_list: a #GHookList.

diff --git a/docs/reference/glib/tmpl/linked_lists_double.sgml b/docs/reference/glib/tmpl/linked_lists_double.sgml
index 8c8c35c..e55b62e 100644 (file)
--- a/docs/reference/glib/tmpl/linked_lists_double.sgml
+++ b/docs/reference/glib/tmpl/linked_lists_double.sgml
@@ -292,6 +292,20 @@ value if the first element comes after the second.
 @Returns: the start of the sorted #GList.
 
 
+<!-- ##### USER_FUNCTION GCompareFunc ##### -->
+<para>
+Specifies the type of a comparison function used to compare two
+values.  The function should return a negative integer if the first
+value comes before the second, 0 if they are equal, or a positive
+integer if the first value comes after the second.
+</para>
+
+@a: a value.
+@b: a value to compare with.
+@Returns: negative value if @a < @b; zero if @a = @b; positive value
+if @a > @b.
+
+
 <!-- ##### FUNCTION g_list_sort_with_data ##### -->
 <para>
 Like g_list_sort(), but the comparison function accepts a user data argument.
@@ -303,7 +317,7 @@ Like g_list_sort(), but the comparison function accepts a user data argument.
 @Returns: the new head of @list.
 
 
-<!-- ##### USER_FUNCTION GCompareFunc ##### -->
+<!-- ##### USER_FUNCTION GCompareDataFunc ##### -->
 <para>
 Specifies the type of a comparison function used to compare two
 values.  The function should return a negative integer if the first
@@ -313,6 +327,7 @@ integer if the first value comes after the second.
 
 @a: a value.
 @b: a value to compare with.
+@user_data: user data to pass to comparison function.
 @Returns: negative value if @a < @b; zero if @a = @b; positive value
 if @a > @b.
 

diff --git a/docs/reference/glib/tmpl/macros_misc.sgml b/docs/reference/glib/tmpl/macros_misc.sgml
index 276a463..11c15a1 100644 (file)
--- a/docs/reference/glib/tmpl/macros_misc.sgml
+++ b/docs/reference/glib/tmpl/macros_misc.sgml
@@ -135,7 +135,12 @@ A const function doesn't examine any values except its parameters,
 and has no effects except its return value.
 See the GNU C documentation for details. 
 </para>
-
+<note><para>
+A function that has pointer arguments and examines the data pointed to 
+must <emphasis>not</emphasis> be declared const. Likewise, a function that 
+calls a non-const function usually must not be const. It doesn't make sense 
+for a const function to return void.
+</para></note>
 
 
 <!-- ##### MACRO G_GNUC_PRINTF ##### -->

diff --git a/docs/reference/glib/tmpl/spawn.sgml b/docs/reference/glib/tmpl/spawn.sgml
index 2e213d3..31a7fb5 100644 (file)
--- a/docs/reference/glib/tmpl/spawn.sgml
+++ b/docs/reference/glib/tmpl/spawn.sgml
@@ -64,10 +64,14 @@ error domains.
 
 <!-- ##### USER_FUNCTION GSpawnChildSetupFunc ##### -->
 <para>
-
+Specifies the type of the setup function passed to g_spawn_async(),
+g_spawn_sync() and g_spawn_async_with_pipes(). It is called in the 
+child after GLib has performed all the setup it plans to perform 
+but before calling <function>exec()</function>. Obviously, actions 
+taken in this function will only affect the child, not the parent.
 </para>
 
-@user_data: 
+@user_data: user data to pass to the function.
 
 
 <!-- ##### FUNCTION g_spawn_async_with_pipes ##### -->

diff --git a/docs/reference/glib/tmpl/trees-binary.sgml b/docs/reference/glib/tmpl/trees-binary.sgml
index 832aa94..ac6094f 100644 (file)
--- a/docs/reference/glib/tmpl/trees-binary.sgml
+++ b/docs/reference/glib/tmpl/trees-binary.sgml
@@ -79,17 +79,6 @@ It should be accessed only by using the following functions.
 @Returns: 
 
 
-<!-- ##### USER_FUNCTION GCompareDataFunc ##### -->
-<para>
-
-</para>
-
-@a: 
-@b: 
-@user_data: 
-@Returns: 
-
-
 <!-- ##### FUNCTION g_tree_insert ##### -->
 <para>