From ff4685caa0334fe9e27b81d21bbfde6572915e0f Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Mon, 10 Mar 2008 16:47:58 +0000 Subject: [PATCH] Remove inlined docs svn path=/trunk/; revision=6656 --- docs/reference/ChangeLog | 6 + .../glib/tmpl/linked_lists_double.sgml | 305 +++++++----------- .../glib/tmpl/linked_lists_single.sgml | 281 ++++++---------- 3 files changed, 220 insertions(+), 372 deletions(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 87f94588..54639fdf 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,9 @@ +2008-03-10 Matthias Clasen + + * glib/tmpl/linked_lists_double.sgml: + * glib/tmpl/linked_lists_single.sgml: Remove docs that have + been inlined. + 2008-03-10 Matthias Clasen * glib/tmpl/types.sgml: Add a Since marker for goffset (#521013, diff --git a/docs/reference/glib/tmpl/linked_lists_double.sgml b/docs/reference/glib/tmpl/linked_lists_double.sgml index d29af022..7163bfa9 100644 --- a/docs/reference/glib/tmpl/linked_lists_double.sgml +++ b/docs/reference/glib/tmpl/linked_lists_double.sgml @@ -81,160 +81,103 @@ The #GList struct is used for each element in a doubly-linked list. -Adds a new element on to the end of the list. - - - -The return value is the new start of the list, which may have changed, so -make sure you store the new value. - - - - -Note that g_list_append() has to traverse the entire list to find the end, -which is inefficient when adding multiple elements. A common idiom to -avoid the inefficiency is to prepend the elements and reverse the list -when all elements have been added. - - - - /* Notice that these are initialized to the empty list. */ - GList *list = NULL, *number_list = NULL; - - /* This is a list of strings. */ - list = g_list_append (list, "first"); - list = g_list_append (list, "second"); - /* This is a list of integers. */ - number_list = g_list_append (number_list, GINT_TO_POINTER (27)); - number_list = g_list_append (number_list, GINT_TO_POINTER (14)); - + -@list: a pointer to a #GList. -@data: the data for the new element. -@Returns: the new start of the #GList. +@list: +@data: +@Returns: -Adds a new element on to the start of the list. - - - -The return value is the new start of the list, which may have changed, so -make sure you store the new value. + - - - /* Notice that it is initialized to the empty list. */ - GList *list = NULL; - list = g_list_prepend (list, "last"); - list = g_list_prepend (list, "first"); - -@list: a pointer to a #GList. -@data: the data for the new element. -@Returns: the new start of the #GList. +@list: +@data: +@Returns: -Inserts a new element into the list at the given position. + -@list: a pointer to a #GList. -@data: the data for the new element. -@position: the position to insert the element. If this is negative, or is -larger than the number of elements in the list, the new element is added on -to the end of the list. -@Returns: the new start of the #GList. +@list: +@data: +@position: +@Returns: -Inserts a new element into the list before the given position. + -@list: a pointer to a #GList. -@sibling: the list element before which the new element is inserted - or %NULL to insert at the end of the list. -@data: the data for the new element. -@Returns: the new start of the #GList. +@list: +@sibling: +@data: +@Returns: -Inserts a new element into the list, using the given comparison function -to determine its position. + -@list: a pointer to a #GList. -@data: the data for the new element. -@func: the function to compare elements in the list. It should return a -number > 0 if the first parameter comes after the second parameter in -the sort order. -@Returns: the new start of the #GList. +@list: +@data: +@func: +@Returns: -Removes an element from a #GList. -If two elements contain the same data, only the first is removed. -If none of the elements contain the data, the #GList is unchanged. + -@list: a #GList. -@data: the data of the element to remove. -@Returns: the new start of the #GList. +@list: +@data: +@Returns: -Removes an element from a #GList, without freeing the element. -The removed element's prev and next links are set to %NULL, so that it becomes a -self-contained list with one element. + -@list: a #GList. -@llink: an element in the #GList. -@Returns: the new start of the #GList, without the element. +@list: +@llink: +@Returns: -Deletes the node @link_ from @list. + -@list: a #GList. -@link_: node to delete from @list. -@Returns: the new head of @list. +@list: +@link_: +@Returns: -Removes all list nodes with data equal to @data. Returns the new -head of the list. Contrast with g_list_remove() which removes only -the first node matching the given data. + -@list: a #GList. -@data: data to remove. -@Returns: new head of @list. +@list: +@data: +@Returns: -Frees all of the memory used by a #GList. -The freed elements are returned to the slice allocator. - - - -If list elements contain dynamically-allocated memory, they should be freed -first. + - -@list: a #GList. +@list: @@ -249,11 +192,10 @@ g_list_insert_sorted() and so is rarely used on its own. -Frees one #GList element. -It is usually used after g_list_remove_link(). + -@list: a #GList element. +@list: @@ -265,48 +207,39 @@ Another name for g_list_free_1(). -Gets the number of elements in a #GList. + -@list: a #GList. -@Returns: the number of elements in the #GList. +@list: +@Returns: -Copies a #GList. - - -Note that this is a "shallow" copy. If the list elements consist of pointers -to data, the pointers are copied but the actual data isn't. + -@list: a #GList. -@Returns: a copy of @list. +@list: +@Returns: -Reverses a #GList. -It simply switches the next and prev pointers of each element. + -@list: a #GList. -@Returns: the start of the reversed #GList. +@list: +@Returns: -Sorts a #GList using the given comparison function. + -@list: a #GList. -@compare_func: the comparison function used to sort the #GList. -This function is passed the data from 2 elements of the #GList and should -return 0 if they are equal, a negative value if the first element -comes before the second, or a positive value if the first element -comes after the second. -@Returns: the start of the sorted #GList. +@list: +@compare_func: +@Returns: @@ -325,29 +258,25 @@ if @a > @b. -Inserts a new element into the list, using the given comparison function -to determine its position. + -@list: a pointer to a #GList. -@data: the data for the new element. -@func: the function to compare elements in the list. It should return a -number > 0 if the first parameter comes after the second parameter in -the sort order. -@user_data: user data to pass to comparison function. -@Returns: the new start of the #GList. -@Since 2.10 +@list: +@data: +@func: +@user_data: +@Returns: -Like g_list_sort(), but the comparison function accepts a user data argument. + -@list: a #GList. -@compare_func: comparison function. -@user_data: user data to pass to comparison function. -@Returns: the new head of @list. +@list: +@compare_func: +@user_data: +@Returns: @@ -367,24 +296,22 @@ if @a > @b. -Adds the second #GList onto the end of the first #GList. -Note that the elements of the second #GList are not copied. -They are used directly. + -@list1: a #GList. -@list2: the #GList to add to the end of the first #GList. -@Returns: the start of the new #GList. +@list1: +@list2: +@Returns: -Calls a function for each element of a #GList. + -@list: a #GList. -@func: the function to call with each element's data. -@user_data: user data to pass to the function. +@list: +@func: +@user_data: @@ -399,21 +326,20 @@ g_slist_foreach(). -Gets the first element in a #GList. + -@list: a #GList. -@Returns: the first element in a #GList, or %NULL if the #GList has no elements. +@list: +@Returns: -Gets the last element in a #GList. + -@list: a #GList. -@Returns: the last element in the #GList, or %NULL if the #GList has no -elements. +@list: +@Returns: @@ -436,82 +362,73 @@ A convenience macro to gets the next element in a #GList. -Gets the element at the given position in a #GList. + -@list: a #GList. -@n: the position of the element, counting from 0. -@Returns: the element, or %NULL if the position is off the end of the #GList. +@list: +@n: +@Returns: -Gets the data of the element at the given position. + -@list: a #GList. -@n: the position of the element. -@Returns: the element's data, or %NULL if the position is off the end of the -#GList. +@list: +@n: +@Returns: -Gets the element @n places before @list. + -@list: a #GList. -@n: the position of the element, counting from 0. -@Returns: the element, or %NULL if the position is off the end of the #GList. +@list: +@n: +@Returns: + - -Finds the element in a #GList which contains the given data. + -@list: a #GList. -@data: the element data to find. -@Returns: the found #GList element, or %NULL if it is not found. +@list: +@data: +@Returns: -Finds an element in a #GList, using a supplied function to find the desired -element. -It iterates over the list, calling the given function which should return 0 -when the desired element is found. -The function takes two #gconstpointer arguments, the #GList element's data as -the first argument and the given user data. + -@list: a #GList. -@data: user data passed to the function. -@func: the function to call for each element. It should return 0 when the -desired element is found. -@Returns: the found #GList element, or %NULL if it is not found. +@list: +@data: +@func: +@Returns: -Gets the position of the given element in the #GList (starting from 0). + -@list: a #GList. -@llink: an element in the #GList. -@Returns: the position of the element in the #GList, or -1 if the element is -not found. +@list: +@llink: +@Returns: -Gets the position of the element containing the given data (starting from 0). + -@list: a #GList. -@data: the data to find. -@Returns: the index of the element containing the data, or -1 if the data -is not found. +@list: +@data: +@Returns: diff --git a/docs/reference/glib/tmpl/linked_lists_single.sgml b/docs/reference/glib/tmpl/linked_lists_single.sgml index e22af418..81f3ecf0 100644 --- a/docs/reference/glib/tmpl/linked_lists_single.sgml +++ b/docs/reference/glib/tmpl/linked_lists_single.sgml @@ -90,162 +90,111 @@ g_slist_insert_sorted() functions and so is rarely used on its own. -Adds a new element on to the end of the list. - - - -The return value is the new start of the list, which may have changed, so -make sure you store the new value. - - - - -Note that g_slist_append() has to traverse the entire list to find the end, -which is inefficient when adding multiple elements. A common idiom to -avoid the inefficiency is to prepend the elements and reverse the list -when all elements have been added. - - - - /* Notice that these are initialized to the empty list. */ - GSList *list = NULL, *number_list = NULL; - /* This is a list of strings. */ - list = g_slist_append (list, "first"); - list = g_slist_append (list, "second"); - - /* This is a list of integers. */ - number_list = g_slist_append (number_list, GINT_TO_POINTER (27)); - number_list = g_slist_append (number_list, GINT_TO_POINTER (14)); - + -@list: a #GSList. -@data: the data for the new element. -@Returns: the new start of the #GSList. +@list: +@data: +@Returns: -Adds a new element on to the start of the list. - - - -The return value is the new start of the list, which may have changed, so -make sure you store the new value. + - - - /* Notice that it is initialized to the empty list. */ - GSList *list = NULL; - list = g_slist_prepend (list, "last"); - list = g_slist_prepend (list, "first"); - -@list: a #GSList. -@data: the data for the new element. -@Returns: the new start of the #GSList. +@list: +@data: +@Returns: -Inserts a new element into the list at the given position. + -@list: a #GSList. -@data: the data for the new element. -@position: the position to insert the element. If this is negative, or is -larger than the number of elements in the list, the new element is added on -to the end of the list. -@Returns: the new start of the #GSList. +@list: +@data: +@position: +@Returns: -Inserts a node before @sibling containing @data. Returns the new head of the list. + -@slist: a #GSList. -@sibling: node to insert @data before. -@data: data to put in the newly-inserted node. -@Returns: new head of the list. +@slist: +@sibling: +@data: +@Returns: -Inserts a new element into the list, using the given comparison function -to determine its position. + -@list: a #GSList. -@data: the data for the new element. -@func: the function to compare elements in the list. It should return a -number > 0 if the first parameter comes after the second parameter in -the sort order. -@Returns: the new start of the #GSList. +@list: +@data: +@func: +@Returns: -Removes an element from a #GSList. -If two elements contain the same data, only the first is removed. -If none of the elements contain the data, the #GSList is unchanged. + -@list: a #GSList. -@data: the data of the element to remove. -@Returns: the new start of the #GSList. + +@data: +@Returns: -Removes an element from a #GSList, without freeing the element. -The removed element's next link is set to %NULL, so that it becomes a -self-contained list with one element. + -@list: a #GSList. -@link_: an element in the #GSList. -@Returns: the new start of the #GSList, without the element. +@list: +@link_: +@Returns: -Deletes a node of @list. Returns the new list head. + -@list: a #GSList. -@link_: node to delete. -@Returns: new head of @list. +@list: +@link_: +@Returns: -Removes all list nodes with data equal to @data. Returns the new -head of the list. Contrast with g_slist_remove() which removes only -the first node matching the given data. + -@list: a #GSList. -@data: data to remove. -@Returns: new head of @list. +@list: +@data: +@Returns: -Frees all of the memory used by a #GSList. -The freed elements are returned to the slice allocator. + -@list: a #GSList. +@list: -Frees one #GSList element. -It is usually used after g_slist_remove_link(). + -@list: a #GSList element. +@list: @@ -258,106 +207,91 @@ A macro which does the same as g_slist_free_1(). -Gets the number of elements in a #GSList. + -@list: a #GSList. -@Returns: the number of elements in the #GSList. +@list: +@Returns: -Copies a #GSList. - - -Note that this is a "shallow" copy. If the list elements consist of pointers -to data, the pointers are copied but the actual data isn't. + -@list: a #GSList. -@Returns: a copy of @list. +@list: +@Returns: -Reverses a #GSList. + -@list: a #GSList. -@Returns: the start of the reversed #GSList. +@list: +@Returns: -Inserts a new element into the list, using the given comparison function -to determine its position. + -@list: a #GSList. -@data: the data for the new element. -@func: the function to compare elements in the list. It should return a -number > 0 if the first parameter comes after the second parameter in -the sort order. -@user_data: data to pass to comparison function. -@Returns: the new start of the #GSList. -@Since 2.10 +@list: +@data: +@func: +@user_data: +@Returns: -Sorts a #GSList using the given comparison function. + -@list: a #GSList. -@compare_func: the comparison function used to sort the #GSList. -This function is passed the data from 2 elements of the #GSList and should -return 0 if they are equal, a negative value if the first element -comes before the second, or a positive value if the first element -comes after the second. -@Returns: the start of the sorted #GSList. +@list: +@compare_func: +@Returns: -Like g_slist_sort(), but the sort function accepts a user data argument. + -@list: a #GSList -@compare_func: comparison function. -@user_data: data to pass to comparison function. -@Returns: new head of the list. +@list: +@compare_func: +@user_data: +@Returns: -Adds the second #GSList onto the end of the first #GSList. -Note that the elements of the second #GSList are not copied. -They are used directly. + -@list1: a #GSList. -@list2: the #GSList to add to the end of the first #GSList. -@Returns: the start of the new #GSList. +@list1: +@list2: +@Returns: -Calls a function for each element of a #GSList. + -@list: a #GSList. -@func: the function to call with each element's data. -@user_data: user data to pass to the function. +@list: +@func: +@user_data: -Gets the last element in a #GSList. + -@list: a #GSList. -@Returns: the last element in the #GSList, or %NULL if the #GSList has no -elements. +@list: +@Returns: @@ -371,72 +305,63 @@ A convenience macro to gets the next element in a #GSList. -Gets the element at the given position in a #GSList. + -@list: a #GSList. -@n: the position of the element, counting from 0. -@Returns: the element, or %NULL if the position is off the end of the #GSList. +@list: +@n: +@Returns: -Gets the data of the element at the given position. + -@list: a #GSList. -@n: the position of the element. -@Returns: the element's data, or %NULL if the position is off the end of the -#GSList. +@list: +@n: +@Returns: -Finds the element in a #GSList which contains the given data. + -@list: a #GSList. -@data: the element data to find. -@Returns: the found #GSList element, or %NULL if it is not found. +@list: +@data: +@Returns: -Finds an element in a #GSList, using a supplied function to find the desired -element. -It iterates over the list, calling the given function which should return 0 -when the desired element is found. -The function takes two #gconstpointer arguments, the #GSList element's data as -the first argument and the given user data. + -@list: a #GSList. -@data: user data passed to the function. -@func: the function to call for each element. It should return 0 when the -desired element is found. -@Returns: the found #GSList element, or %NULL if it is not found. +@list: +@data: +@func: +@Returns: -Gets the position of the given element in the #GSList (starting from 0). + -@list: a #GSList. -@llink: an element in the #GSList. -@Returns: the position of the element in the #GSList, or -1 if the element -is not found. +@list: +@llink: +@Returns: -Gets the position of the element containing the given data (starting from 0). + -@list: a #GSList. -@data: the data to find. -@Returns: the index of the element containing the data, or -1 if the data -is not found. +@list: +@data: +@Returns: -- 2.34.1