Fixes and corrections

svn path=/trunk/; revision=5838

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 9afe5d9..09a3fec 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,5 +1,9 @@
 2007-11-08  Matthias Clasen <mclasen@redhat.com>
 
+       * glib/tmpl/hooks.sgml: Cleanups and fixes
+
+2007-11-08  Matthias Clasen <mclasen@redhat.com>
+
        * glib/tmpl/thread_pools.sgml: Fix the GThreadPool docs. 
        (#491959, Areg Beketovski)
 

diff --git a/docs/reference/glib/tmpl/hooks.sgml b/docs/reference/glib/tmpl/hooks.sgml
index 8617129..c359611 100644 (file)
--- a/docs/reference/glib/tmpl/hooks.sgml
+++ b/docs/reference/glib/tmpl/hooks.sgml
@@ -26,13 +26,13 @@ The <structname>GHookList</structname> struct represents a
 list of hook functions.
 </para>
 
-@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.
+@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
 @dummy3: unused
 @finalize_hook: the function to call to finalize a #GHook element. The
-default behaviour is to call the hooks <function>destroy</function> function.
+default behaviour is to call the hooks <function>destroy</function> function
 @dummy: unused
 
 <!-- ##### USER_FUNCTION GHookFinalizeFunc ##### -->
@@ -41,8 +41,8 @@ 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.
+@hook_list: a #GHookList
+@hook: the hook in @hook_list that gets finalized
 
 
 <!-- ##### STRUCT GHook ##### -->
@@ -51,17 +51,17 @@ 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.
+@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.
+    predefined flags
 @func: the function to call when this hook is invoked. The possible 
-signatures for this function are #GHookFunc and #GHookCheckFunc.
+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.
+#GHookList calls this member of the hook that is being finalized
 
 <!-- ##### USER_FUNCTION GHookFunc ##### -->
 <para>
@@ -69,7 +69,7 @@ Defines the type of a hook function that can be invoked
 by g_hook_list_invoke().
 </para>
 
-@data: the data field of the #GHook is passed to the hook function here.
+@data: the data field of the #GHook is passed to the hook function here
 
 
 <!-- ##### USER_FUNCTION GHookCheckFunc ##### -->
@@ -78,8 +78,8 @@ Defines the type of a hook function that can be invoked
 by g_hook_list_invoke_check().
 </para>
 
-@data: the data field of the #GHook is passed to the hook function here.
-@Returns: %FALSE if the #GHook should be destroyed.
+@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 ##### -->
@@ -88,9 +88,9 @@ Initializes a #GHookList.
 This must be called before the #GHookList is used.
 </para>
 
-@hook_list: a #GHookList.
+@hook_list: a #GHookList
 @hook_size: the size of each element in the #GHookList, typically
-<literal>sizeof (GHook)</literal>.
+    <literal>sizeof (GHook)</literal>
 
 
 <!-- ##### FUNCTION g_hook_list_invoke ##### -->
@@ -98,9 +98,9 @@ This must be called before the #GHookList is used.
 Calls all of the #GHook functions in a #GHookList.
 </para>
 
-@hook_list: a #GHookList.
+@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.
+    thread) can be called. If set to %FALSE, these are skipped
 
 
 <!-- ##### FUNCTION g_hook_list_invoke_check ##### -->
@@ -109,9 +109,9 @@ Calls all of the #GHook functions in a #GHookList.
 Any function which returns %TRUE is removed from the #GHookList.
 </para>
 
-@hook_list: a #GHookList.
+@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.
+thread) can be called. If set to %FALSE, these are skipped
 
 
 <!-- ##### FUNCTION g_hook_list_marshal ##### -->
@@ -119,11 +119,11 @@ thread) can be called. If set to %FALSE, these are skipped.
 Calls a function on each valid #GHook. 
 </para>
 
-@hook_list: a #GHookList.
+@hook_list: a #GHookList
 @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.
+    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 GHookMarshaller ##### -->
@@ -131,8 +131,8 @@ thread) are considered valid. If set to %FALSE, these are skipped.
 Defines the type of function used by g_hook_list_marshal().
 </para>
 
-@hook: a #GHook.
-@marshal_data: user data.
+@hook: a #GHook
+@marshal_data: user data
 
 
 <!-- ##### FUNCTION g_hook_list_marshal_check ##### -->
@@ -141,11 +141,11 @@ Calls a function on each valid #GHook and destroys it if the
 function returns %FALSE.
 </para>
 
-@hook_list: a #GHookList.
+@hook_list: a #GHookList
 @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.
+    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 ##### -->
@@ -153,9 +153,9 @@ thread) are considered valid. If set to %FALSE, these are skipped.
 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.
+@hook: a #GHook
+@marshal_data: user data
+@Returns: %FALSE if @hook should be destroyed
 
 
 <!-- ##### FUNCTION g_hook_list_clear ##### -->
@@ -163,7 +163,7 @@ Defines the type of function used by g_hook_list_marshal_check().
 Removes all the #GHook elements from a #GHookList.
 </para>
 
-@hook_list: a #GHookList.
+@hook_list: a #GHookList
 
 
 <!-- ##### FUNCTION g_hook_alloc ##### -->
@@ -171,8 +171,8 @@ Removes all the #GHook elements from a #GHookList.
 Allocates space for a #GHook and initializes it.
 </para>
 
-@hook_list: a #GHookList.
-@Returns: a new #GHook.
+@hook_list: a #GHookList
+@Returns: a new #GHook
 
 
 <!-- ##### MACRO g_hook_append ##### -->
@@ -180,8 +180,8 @@ Allocates space for a #GHook and initializes it.
 Appends a #GHook onto the end of a #GHookList.
 </para>
 
-@hook_list: a #GHookList.
-@hook: the #GHook to add to the end of @hook_list.
+@hook_list: a #GHookList
+@hook: the #GHook to add to the end of @hook_list
 
 
 <!-- ##### FUNCTION g_hook_prepend ##### -->
@@ -189,8 +189,8 @@ Appends a #GHook onto the end of a #GHookList.
 Prepends a #GHook on the start of a #GHookList.
 </para>
 
-@hook_list: a #GHookList.
-@hook: the #GHook to add to the start of @hook_list.
+@hook_list: a #GHookList
+@hook: the #GHook to add to the start of @hook_list
 
 
 <!-- ##### FUNCTION g_hook_insert_before ##### -->
@@ -198,9 +198,9 @@ Prepends a #GHook on the start of a #GHookList.
 Inserts a #GHook into a #GHookList, before a given #GHook.
 </para>
 
-@hook_list: a #GHookList.
-@sibling: the #GHook to insert the new #GHook before.
-@hook: the #GHook to insert.
+@hook_list: a #GHookList
+@sibling: the #GHook to insert the new #GHook before
+@hook: the #GHook to insert
 
 
 <!-- ##### FUNCTION g_hook_insert_sorted ##### -->
@@ -208,9 +208,9 @@ Inserts a #GHook into a #GHookList, before a given #GHook.
 Inserts a #GHook into a #GHookList, sorted by the given function.
 </para>
 
-@hook_list: a #GHookList.
-@hook: the #GHook to insert.
-@func: the comparison function used to sort the #GHook elements.
+@hook_list: a #GHookList
+@hook: the #GHook to insert
+@func: the comparison function used to sort the #GHook elements
 
 
 <!-- ##### USER_FUNCTION GHookCompareFunc ##### -->
@@ -219,9 +219,9 @@ Defines the type of function used to compare #GHook elements in
 g_hook_insert_sorted().
 </para>
 
-@new_hook: the #GHook being inserted.
-@sibling: the #GHook to compare with @new_hook.
-@Returns: a value &lt;= 0 if @new_hook should be before @sibling.
+@new_hook: the #GHook being inserted
+@sibling: the #GHook to compare with @new_hook
+@Returns: a value &lt;= 0 if @new_hook should be before @sibling
 
 
 <!-- ##### FUNCTION g_hook_compare_ids ##### -->
@@ -230,9 +230,9 @@ Compares the ids of two #GHook elements, returning a negative value
 if the second id is greater than the first.
 </para>
 
-@new_hook: a #GHook.
-@sibling: a #GHook to compare with @new_hook.
-@Returns: a value &lt;= 0 if the id of @sibling is >= the id of @new_hook.
+@new_hook: a #GHook
+@sibling: a #GHook to compare with @new_hook
+@Returns: a value &lt;= 0 if the id of @sibling is >= the id of @new_hook
 
 
 <!-- ##### FUNCTION g_hook_get ##### -->
@@ -240,9 +240,9 @@ if the second id is greater than the first.
 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.
+@hook_list: a #GHookList
+@hook_id: a hook id
+@Returns: the #GHook with the given id, or %NULL if it is not found
 
 
 <!-- ##### FUNCTION g_hook_find ##### -->
@@ -250,13 +250,13 @@ Returns the #GHook with the given id, or %NULL if it is not found.
 Finds a #GHook in a #GHookList using the given function to test for a match.
 </para>
 
-@hook_list: a #GHookList.
+@hook_list: a #GHookList
 @need_valids: %TRUE if #GHook elements which have been destroyed should be
-skipped.
+    skipped
 @func: the function to call for each #GHook, which should return %TRUE when
-the #GHook has been found.
-@data: the data to pass to @func.
-@Returns: the found #GHook or %NULL if no matching #GHook is found.
+    the #GHook has been found
+@data: the data to pass to @func
+@Returns: the found #GHook or %NULL if no matching #GHook is found
 
 
 <!-- ##### USER_FUNCTION GHookFindFunc ##### -->
@@ -264,9 +264,9 @@ the #GHook has been found.
 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.
+@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 ##### -->
@@ -274,12 +274,12 @@ Defines the type of the function passed to g_hook_find().
 Finds a #GHook in a #GHookList with the given data.
 </para>
 
-@hook_list: a #GHookList.
+@hook_list: a #GHookList
 @need_valids: %TRUE if #GHook elements which have been destroyed should be
-skipped.
-@data: the data to find.
+    skipped
+@data: the data to find
 @Returns: the #GHook with the given @data or %NULL if no matching
-#GHook is found.
+    #GHook is found
 
 
 <!-- ##### FUNCTION g_hook_find_func ##### -->
@@ -287,12 +287,12 @@ skipped.
 Finds a #GHook in a #GHookList with the given function.
 </para>
 
-@hook_list: a #GHookList.
+@hook_list: a #GHookList
 @need_valids: %TRUE if #GHook elements which have been destroyed should be
-skipped.
-@func: the function to find.
+    skipped
+@func: the function to find
 @Returns: the #GHook with the given @func or %NULL if no matching
-#GHook is found.
+    #GHook is found
 
 
 <!-- ##### FUNCTION g_hook_find_func_data ##### -->
@@ -300,13 +300,13 @@ skipped.
 Finds a #GHook in a #GHookList with the given function and data.
 </para>
 
-@hook_list: a #GHookList.
+@hook_list: a #GHookList
 @need_valids: %TRUE if #GHook elements which have been destroyed should be
-skipped.
-@func: the function to find.
-@data: the data to find.
+    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
-#GHook is found.
+    #GHook is found
 
 
 <!-- ##### FUNCTION g_hook_first_valid ##### -->
@@ -317,10 +317,10 @@ g_hook_unref() to restore it when no longer needed. (Or call
 g_hook_next_valid() if you are stepping through the #GHookList.)
 </para>
 
-@hook_list: a #GHookList.
+@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.
+    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 ##### -->
@@ -332,11 +332,11 @@ g_hook_next_valid() until %NULL is returned.)
 
 </para>
 
-@hook_list: a #GHookList.
-@hook: the current #GHook.
+@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.
+    thread) are considered valid. If set to %FALSE, these are skipped
+@Returns: the next valid #GHook, or %NULL if none are valid
 
 
 <!-- ##### ENUM GHookFlagMask ##### -->
@@ -344,9 +344,9 @@ thread) are considered valid. If set to %FALSE, these are skipped.
 Flags used internally in the #GHook implementation.
 </para>
 
-@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: A mask covering all bits reserved for 
+@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: A mask covering all bits reserved for
   hook flags; see #G_HOOK_FLAGS_USER_SHIFT
 
 <!-- ##### MACRO G_HOOK_FLAGS ##### -->
@@ -354,7 +354,7 @@ Flags used internally in the #GHook implementation.
 Returns the flags of a hook.
 </para>
 
-@hook: a #GHook.
+@hook: a #GHook
 
 
 <!-- ##### MACRO G_HOOK_FLAG_USER_SHIFT ##### -->
@@ -372,7 +372,7 @@ which can be used for application-defined flags.
 Casts a pointer to a <literal>GHook*</literal>.
 </para>
 
-@hook: a pointer.
+@hook: a pointer
 
 
 <!-- ##### MACRO G_HOOK_IS_VALID ##### -->
@@ -381,8 +381,8 @@ 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.
+@hook: a #GHook
+@Returns: %TRUE if the #GHook is valid
 
 
 <!-- ##### MACRO G_HOOK_ACTIVE ##### -->
@@ -391,8 +391,8 @@ 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.
+@hook: a #GHook
+@Returns: %TRUE if the #GHook is active
 
 
 <!-- ##### MACRO G_HOOK_IN_CALL ##### -->
@@ -400,8 +400,8 @@ is destroyed.
 Returns %TRUE if the #GHook function is currently executing.
 </para>
 
-@hook: a #GHook.
-@Returns: %TRUE if the #GHook function is currently executing.
+@hook: a #GHook
+@Returns: %TRUE if the #GHook function is currently executing
 
 
 <!-- ##### MACRO G_HOOK_IS_UNLINKED ##### -->
@@ -410,8 +410,8 @@ Returns %TRUE if the #GHook is not in a #GHookList.
 
 </para>
 
-@hook: a #GHook.
-@Returns: %TRUE if the #GHook is not in a #GHookList.
+@hook: a #GHook
+@Returns: %TRUE if the #GHook is not in a #GHookList
 
 
 <!-- ##### FUNCTION g_hook_ref ##### -->
@@ -419,8 +419,8 @@ Returns %TRUE if the #GHook is not in a #GHookList.
 Increments the reference count for a #GHook.
 </para>
 
-@hook_list: a #GHookList.
-@hook: the #GHook to increment the reference count of.
+@hook_list: a #GHookList
+@hook: the #GHook to increment the reference count of
 @Returns: the @hook that was passed in (since 2.6)
 
 
@@ -431,18 +431,18 @@ If the reference count falls to 0, the #GHook is removed from the #GHookList
 and g_hook_free() is called to free it.
 </para>
 
-@hook_list: a #GHookList.
-@hook: the #GHook to unref.
+@hook_list: a #GHookList
+@hook: the #GHook to unref
 
 
 <!-- ##### FUNCTION g_hook_free ##### -->
 <para>
-Calls the #GHookList @hook_free function if it exists, and frees the memory
+Calls the #GHookList @finalize_hook function if it exists, and frees the memory
 allocated for the #GHook.
 </para>
 
-@hook_list: a #GHookList.
-@hook: the #GHook to free.
+@hook_list: a #GHookList
+@hook: the #GHook to free
 
 
 <!-- ##### FUNCTION g_hook_destroy ##### -->
@@ -450,9 +450,9 @@ allocated for the #GHook.
 Destroys a #GHook, given its ID.
 </para>
 
-@hook_list: a #GHookList.
-@hook_id: a hook ID.
-@Returns: %TRUE if the #GHook was found in the #GHookList and destroyed.
+@hook_list: a #GHookList
+@hook_id: a hook ID
+@Returns: %TRUE if the #GHook was found in the #GHookList and destroyed
 
 
 <!-- ##### FUNCTION g_hook_destroy_link ##### -->
@@ -461,7 +461,7 @@ Removes one #GHook from a #GHookList, marking it inactive and calling
 g_hook_unref() on it. 
 </para>
 
-@hook_list: a #GHookList.
-@hook: the #GHook to remove.
+@hook_list: a #GHookList
+@hook: the #GHook to remove