From f1675bbcc7b22c34f55b7f21cca1cfbacf6dfc4b Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Fri, 9 Nov 2007 03:21:27 +0000 Subject: [PATCH] Fixes and corrections svn path=/trunk/; revision=5838 --- docs/reference/ChangeLog | 4 + docs/reference/glib/tmpl/hooks.sgml | 224 ++++++++++++++++++------------------ 2 files changed, 116 insertions(+), 112 deletions(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 9afe5d9..09a3fec 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,5 +1,9 @@ 2007-11-08 Matthias Clasen + * glib/tmpl/hooks.sgml: Cleanups and fixes + +2007-11-08 Matthias Clasen + * 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 --- a/docs/reference/glib/tmpl/hooks.sgml +++ b/docs/reference/glib/tmpl/hooks.sgml @@ -26,13 +26,13 @@ The GHookList struct represents a list of hook functions. -@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 destroy function. +default behaviour is to call the hooks destroy function @dummy: unused @@ -41,8 +41,8 @@ Defines the type of function to be called when a hook in a list of hooks gets finalized. -@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 @@ -51,17 +51,17 @@ The GHook struct represents a single hook function in a #GHookList. -@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 finalize_hook 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 @@ -69,7 +69,7 @@ Defines the type of a hook function that can be invoked by g_hook_list_invoke(). -@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 @@ -78,8 +78,8 @@ Defines the type of a hook function that can be invoked by g_hook_list_invoke_check(). -@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 @@ -88,9 +88,9 @@ Initializes a #GHookList. This must be called before the #GHookList is used. -@hook_list: a #GHookList. +@hook_list: a #GHookList @hook_size: the size of each element in the #GHookList, typically -sizeof (GHook). + sizeof (GHook) @@ -98,9 +98,9 @@ This must be called before the #GHookList is used. Calls all of the #GHook functions in a #GHookList. -@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 @@ -109,9 +109,9 @@ Calls all of the #GHook functions in a #GHookList. Any function which returns %TRUE is removed from the #GHookList. -@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 @@ -119,11 +119,11 @@ thread) can be called. If set to %FALSE, these are skipped. Calls a function on each valid #GHook. -@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 @@ -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(). -@hook: a #GHook. -@marshal_data: user data. +@hook: a #GHook +@marshal_data: user data @@ -141,11 +141,11 @@ Calls a function on each valid #GHook and destroys it if the function returns %FALSE. -@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 @@ -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(). -@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 @@ -163,7 +163,7 @@ Defines the type of function used by g_hook_list_marshal_check(). Removes all the #GHook elements from a #GHookList. -@hook_list: a #GHookList. +@hook_list: a #GHookList @@ -171,8 +171,8 @@ Removes all the #GHook elements from a #GHookList. Allocates space for a #GHook and initializes it. -@hook_list: a #GHookList. -@Returns: a new #GHook. +@hook_list: a #GHookList +@Returns: a new #GHook @@ -180,8 +180,8 @@ Allocates space for a #GHook and initializes it. Appends a #GHook onto the end of a #GHookList. -@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 @@ -189,8 +189,8 @@ Appends a #GHook onto the end of a #GHookList. Prepends a #GHook on the start of a #GHookList. -@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 @@ -198,9 +198,9 @@ Prepends a #GHook on the start of a #GHookList. Inserts a #GHook into a #GHookList, before a given #GHook. -@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 @@ -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. -@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 @@ -219,9 +219,9 @@ Defines the type of function used to compare #GHook elements in g_hook_insert_sorted(). -@new_hook: the #GHook being inserted. -@sibling: the #GHook to compare with @new_hook. -@Returns: a value <= 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 <= 0 if @new_hook should be before @sibling @@ -230,9 +230,9 @@ Compares the ids of two #GHook elements, returning a negative value if the second id is greater than the first. -@new_hook: a #GHook. -@sibling: a #GHook to compare with @new_hook. -@Returns: a value <= 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 <= 0 if the id of @sibling is >= the id of @new_hook @@ -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. -@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 @@ -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. -@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 @@ -264,9 +264,9 @@ the #GHook has been found. Defines the type of the function passed to g_hook_find(). -@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 @@ -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. -@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 @@ -287,12 +287,12 @@ skipped. Finds a #GHook in a #GHookList with the given function. -@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 @@ -300,13 +300,13 @@ skipped. Finds a #GHook in a #GHookList with the given function and data. -@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 @@ -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.) -@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 @@ -332,11 +332,11 @@ g_hook_next_valid() until %NULL is returned.) -@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 @@ -344,9 +344,9 @@ thread) are considered valid. If set to %FALSE, these are skipped. Flags used internally in the #GHook implementation. -@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 @@ -354,7 +354,7 @@ Flags used internally in the #GHook implementation. Returns the flags of a hook. -@hook: a #GHook. +@hook: a #GHook @@ -372,7 +372,7 @@ which can be used for application-defined flags. Casts a pointer to a GHook*. -@hook: a pointer. +@hook: a pointer @@ -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. -@hook: a #GHook. -@Returns: %TRUE if the #GHook is valid. +@hook: a #GHook +@Returns: %TRUE if the #GHook is valid @@ -391,8 +391,8 @@ Returns %TRUE if the #GHook is active, which is normally %TRUE until the #GHook is destroyed. -@hook: a #GHook. -@Returns: %TRUE if the #GHook is active. +@hook: a #GHook +@Returns: %TRUE if the #GHook is active @@ -400,8 +400,8 @@ is destroyed. Returns %TRUE if the #GHook function is currently executing. -@hook: a #GHook. -@Returns: %TRUE if the #GHook function is currently executing. +@hook: a #GHook +@Returns: %TRUE if the #GHook function is currently executing @@ -410,8 +410,8 @@ Returns %TRUE if the #GHook is not in a #GHookList. -@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 @@ -419,8 +419,8 @@ Returns %TRUE if the #GHook is not in a #GHookList. Increments the reference count for a #GHook. -@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. -@hook_list: a #GHookList. -@hook: the #GHook to unref. +@hook_list: a #GHookList +@hook: the #GHook to unref -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. -@hook_list: a #GHookList. -@hook: the #GHook to free. +@hook_list: a #GHookList +@hook: the #GHook to free @@ -450,9 +450,9 @@ allocated for the #GHook. 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. +@hook_list: a #GHookList +@hook_id: a hook ID +@Returns: %TRUE if the #GHook was found in the #GHookList and destroyed @@ -461,7 +461,7 @@ Removes one #GHook from a #GHookList, marking it inactive and calling g_hook_unref() on it. -@hook_list: a #GHookList. -@hook: the #GHook to remove. +@hook_list: a #GHookList +@hook: the #GHook to remove -- 2.7.4