From 6af390c1e598d68fdfca64a6b8fc4c1c3128ae2b Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 4 Oct 2001 22:26:23 +0000 Subject: [PATCH] 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. --- docs/reference/ChangeLog | 8 + docs/reference/glib/glib-sections.txt | 12 +- docs/reference/glib/tmpl/hooks.sgml | 237 +++++++++++----------- docs/reference/glib/tmpl/linked_lists_double.sgml | 17 +- docs/reference/glib/tmpl/macros_misc.sgml | 7 +- docs/reference/glib/tmpl/spawn.sgml | 8 +- docs/reference/glib/tmpl/trees-binary.sgml | 11 - 7 files changed, 160 insertions(+), 140 deletions(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 5cc1201..a48955c 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,11 @@ +2001-10-05 Matthias Clasen + + * 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 * 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 --- a/docs/reference/glib/glib-sections.txt +++ b/docs/reference/glib/glib-sections.txt @@ -1048,19 +1048,19 @@ g_date_sunday_weeks_in_year Hook Functions hooks GHookList +GHookFinalizeFunc GHook GHookFunc GHookCheckFunc -GHookMarshaller -GHookCheckMarshaller -GHookFinalizeFunc 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 @@ -1075,9 +1075,9 @@ g_hook_compare_ids g_hook_get g_hook_find +GHookFindFunc g_hook_find_data g_hook_find_func -GHookFindFunc g_hook_find_func_data @@ -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 --- 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. -#GHookFreeFunc hook_free; -the function to call to free a #GHook element. - - - -#GHookFreeFunc hook_destroy; -the function to call to destory a #GHook element. +#GHookFinalizeFunc finalize_hook; +the function to call to finalize a #GHook element. +The default behaviour is to call the hooks destroy +function. @@ -70,6 +67,17 @@ and the list of hook functions can be invoked. @hook_memchunk: @finalize_hook: + + + +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. + + @@ -79,42 +87,45 @@ and the list of hook functions can be invoked. #gpointer data; -. +data which is passed to func when this hook is invoked. #GHook *next; -. +pointer to the next hook in the list. #GHook *prev; -. +pointer to the previous hook in the list. #guint ref_count; -. +the reference count of this hook. #guint hook_id; -. +the id of this hook, which is unique within its list. #guint flags; -. +flags which are set for this hook. See #GHookFlagMask for +predefined flags. -#gpointer data; -. +#gpointer func; +the function to call when this hook is invoked. The possible +signatures for this function are #GHookFunc and #GHookCheckFunc. #GDestroyNotify destroy; -. +the default finalize_hook function of a +#GHookList calls this member of the hook that is being finalized. @@ -131,51 +142,21 @@ and the list of hook functions can be invoked. - +Defines the type of a hook function that can be invoked +by g_hook_list_invoke(). -@data: +@data: the data field of the #GHook is passed to the hook function here. - - - -@data: -@Returns: - - - - - - - -@hook: -@marshal_data: - -@data: - - - - - - - -@hook: -@marshal_data: -@Returns: - -@data: - - - - - +Defines the type of a hook function that can be invoked +by g_hook_list_invoke_check(). -@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. @@ -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). +sizeof (GHook). @@ -195,45 +176,63 @@ Calls all of the #GHook functions in 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. +@may_recurse: %TRUE if functions which are already running (e.g. in another +thread) can be called. If set to %FALSE, these are skipped. 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. @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. - +Calls a function on each valid #GHook. @hook_list: a #GHookList. -@may_recurse: -@marshaller: -@marshal_data: - -@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. - + +Defines the type of function used by g_hook_list_marshal(). + +@hook: a #GHook. +@marshal_data: user data. + + + + +Calls a function on each valid #GHook and destroys it if the +function returns %FALSE. @hook_list: a #GHookList. -@may_recurse: -@marshaller: -@marshal_data: - -@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. + + + + +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. @@ -315,12 +314,12 @@ if the second id is greater than the first. -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. @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. @@ -329,12 +328,22 @@ Finds a #GHook in a #GHookList using the given function to test for a match. @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. + + + + +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. @@ -343,10 +352,10 @@ Finds a #GHook in a #GHookList with the given data. @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. @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. - - -Defines the type of the function passed to g_hooK_find_func(). - - -@hook: a #GHook. -@data: user data passed to g_hook_find_func(). -@Returns: TRUE if the required #GHook has been found. - - Finds a #GHook in a #GHookList with the given function and data. @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.) @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. @@ -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.) @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. - +Flags used internally in the #GHook implementation. -@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: - +Returns the flags of a hook. -@hook: +@hook: a #GHook. @@ -443,49 +442,49 @@ thread) are considered valid. If set to FALSE, these are skipped. - +Casts a pointer to a GHook*. -@hook: +@hook: a pointer. -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. @hook: a #GHook. -@Returns: TRUE if the #GHook is valid. +@Returns: %TRUE if the #GHook is valid. -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. @hook: a #GHook. -@Returns: TRUE if the #GHook is active. +@Returns: %TRUE if the #GHook is active. -Returns TRUE if the #GHook function is currently executing. +Returns %TRUE if the #GHook function is currently executing. @hook: a #GHook. -@Returns: TRUE if the #GHook function is currently executing. +@Returns: %TRUE if the #GHook function is currently executing. -Returns TRUE if the #GHook is not in a #GHookList. +Returns %TRUE if the #GHook is not in a #GHookList. @hook: a #GHook. -@Returns: TRUE if the #GHook is not in a #GHookList. +@Returns: %TRUE if the #GHook is not in a #GHookList. @@ -505,7 +504,7 @@ and g_hook_free() is called to free it. @hook_list: a #GHookList. -@hook: +@hook: the #GHook to unref. @@ -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. -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. @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 --- 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. + + +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. + + +@a: a value. +@b: a value to compare with. +@Returns: negative value if @a < @b; zero if @a = @b; positive value +if @a > @b. + + 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. - + 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 --- 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. - + +A function that has pointer arguments and examines the data pointed to +must not 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. + diff --git a/docs/reference/glib/tmpl/spawn.sgml b/docs/reference/glib/tmpl/spawn.sgml index 2e213d3..31a7fb5 100644 --- a/docs/reference/glib/tmpl/spawn.sgml +++ b/docs/reference/glib/tmpl/spawn.sgml @@ -64,10 +64,14 @@ error domains. - +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 exec(). Obviously, actions +taken in this function will only affect the child, not the parent. -@user_data: +@user_data: user data to pass to the function. diff --git a/docs/reference/glib/tmpl/trees-binary.sgml b/docs/reference/glib/tmpl/trees-binary.sgml index 832aa94..ac6094f 100644 --- 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: - - - - - -@a: -@b: -@user_data: -@Returns: - - -- 2.7.4