From 42d4554111f6bdd240286d6801008b1df2d1d737 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Fri, 28 Sep 2001 21:33:14 +0000 Subject: [PATCH] Documented some functions, markup fixes. New file. Add entity for * glib/tmpl/warnings.sgml, glib/tmpl/linked_lists_double.sgml, glib/tmpl/completion.sgml, glib/tmpl/strings.sgml: Documented some functions, markup fixes. * glib/tmpl/patterns.sgml: New file. * glib/glib-docs.sgml: Add entity for patterns.sgml. --- docs/reference/ChangeLog | 8 +++ docs/reference/glib/glib-docs.sgml | 2 + docs/reference/glib/tmpl/completion.sgml | 30 ++++---- docs/reference/glib/tmpl/linked_lists_double.sgml | 63 ++++++++--------- docs/reference/glib/tmpl/strings.sgml | 84 ++++++++++++----------- docs/reference/glib/tmpl/warnings.sgml | 39 ++++++----- 6 files changed, 125 insertions(+), 101 deletions(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 084c1f0..4c43999 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,11 @@ +2001-09-27 Matthias Clasen + + * glib/tmpl/warnings.sgml, glib/tmpl/linked_lists_double.sgml, + glib/tmpl/completion.sgml, glib/tmpl/strings.sgml: Documented + some functions, markup fixes. + * glib/tmpl/patterns.sgml: New file. + * glib/glib-docs.sgml: Add entity for patterns.sgml. + 2001-09-26 Matthias Clasen * glib/glib-sections.txt: Add g_mem_is_system_malloc. diff --git a/docs/reference/glib/glib-docs.sgml b/docs/reference/glib/glib-docs.sgml index 6c5c5f3..67df7d5 100644 --- a/docs/reference/glib/glib-docs.sgml +++ b/docs/reference/glib/glib-docs.sgml @@ -10,6 +10,7 @@ + @@ -97,6 +98,7 @@ &glib-Spawn; &glib-Fileutils; &glib-Shell; + &glib-Pattern-Matching; &glib-Markup; &glib-Windows-Compatability-Functions; diff --git a/docs/reference/glib/tmpl/completion.sgml b/docs/reference/glib/tmpl/completion.sgml index 6868433..5fb26bf 100644 --- a/docs/reference/glib/tmpl/completion.sgml +++ b/docs/reference/glib/tmpl/completion.sgml @@ -23,6 +23,8 @@ Items in the completion can be simple strings (e.g. file names), or pointers to arbitrary data structures. If data structures are used you must provide a #GCompletionFunc in g_completion_new(), which retrieves the item's string from the data structure. +You can change the way in which strings are compared by setting +a different #GCompletionStrncmpFunc in g_completion_set_compare(). @@ -55,7 +57,7 @@ Creates a new #GCompletion. @func: the function to be called to return the string representing an item -in the #GCompletion, or NULL if strings are going to be used as the +in the #GCompletion, or %NULL if strings are going to be used as the #GCompletion items. @Returns: the new #GCompletion. @@ -105,8 +107,8 @@ Attempts to complete the string @prefix using the #GCompletion target items. @cmp: the #GCompletion. @prefix: the prefix string, typically typed by the user, which is compared with each of the items. -@new_prefix: if non-NULL, returns the longest prefix which is common to all -items that matched @prefix, or NULL if no items matched @prefix. +@new_prefix: if non-%NULL, returns the longest prefix which is common to all +items that matched @prefix, or %NULL if no items matched @prefix. This string should be freed when no longer needed. @Returns: the list of items whose strings begin with @prefix. This should not be changed. @@ -114,24 +116,28 @@ not be changed. - +Sets the function to use for string comparisons. The default +string comparison function is strncmp(). -@cmp: -@strncmp_func: +@cmp: a #GCompletion. +@strncmp_func: the string comparison function. - +Specifies the type of the function passed to g_completion_set_compare(). +This is used when you use strings as #GCompletion items. -@s1: -@s2: -@n: -@Returns: - +@s1: string to compare with @s2. +@s2: string to compare with @s1. +@n: maximal number of bytes to compare. +@Returns: an integer less than, equal to, or greater than zero if the +first @n bytes of @s1 is found, respectively, to be less than, to match, +or to be greater than the first @n bytes of @s2. + Frees all memory used by the #GCompletion. diff --git a/docs/reference/glib/tmpl/linked_lists_double.sgml b/docs/reference/glib/tmpl/linked_lists_double.sgml index c76abd8..8c8c35c 100644 --- a/docs/reference/glib/tmpl/linked_lists_double.sgml +++ b/docs/reference/glib/tmpl/linked_lists_double.sgml @@ -34,8 +34,8 @@ the first element in the list. The functions which insert elements return the new start of the list, which may have changed. -There is no function to create a #GList. NULL is considered to be the empty -list so you simply set a #GList* to NULL. +There is no function to create a #GList. %NULL is considered to be the empty +list so you simply set a #GList* to %NULL. To add elements, use g_list_append(), g_list_prepend(), g_list_insert() @@ -143,13 +143,14 @@ to the end of the list. - +Inserts a new element into the list before the given position. -@list: -@sibling: -@data: -@Returns: +@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. @@ -181,7 +182,7 @@ If none of the elements contain the data, the #GList is unchanged. 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 +The removed element's prev and next links are set to %NULL, so that it becomes a self-contained list with one element. @@ -195,9 +196,9 @@ self-contained list with one element. Deletes the node @link from @list. -@list: a #GList -@link: node to delete from @list -@Returns: the new head of @list +@list: a #GList. +@link: node to delete from @list. +@Returns: the new head of @list. @@ -207,9 +208,9 @@ 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: a #GList. +@data: data to remove. +@Returns: new head of @list. @@ -224,7 +225,7 @@ first. -@list: +@list: a #GList. @@ -296,10 +297,10 @@ value if the first element comes after the second. 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: a #GList. +@compare_func: comparison function. +@user_data: user data to pass to comparison function. +@Returns: the new head of @list. @@ -354,7 +355,7 @@ 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. +@Returns: the first element in a #GList, or %NULL if the #GList has no elements. @@ -363,7 +364,7 @@ Gets the last element in a #GList. @list: a #GList. -@Returns: the last element in the #GList, or NULL if the #GList has no +@Returns: the last element in the #GList, or %NULL if the #GList has no elements. @@ -373,7 +374,7 @@ A convenience macro to gets the previous element in a #GList. @list: an element in a #GList. -@Returns: the previous element, or NULL if there are no previous elements. +@Returns: the previous element, or %NULL if there are no previous elements. @@ -382,7 +383,7 @@ A convenience macro to gets the next element in a #GList. @list: an element in a #GList. -@Returns: the next element, or NULL if there are no more elements. +@Returns: the next element, or %NULL if there are no more elements. @@ -392,7 +393,7 @@ 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. +@Returns: the element, or %NULL if the position is off the end of the #GList. @@ -402,18 +403,18 @@ 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 +@Returns: the element's data, or %NULL if the position is off the end of the #GList. - +Gets the element @n places before @list. -@list: -@n: -@Returns: +@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. @@ -423,7 +424,7 @@ 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. +@Returns: the found #GList element, or %NULL if it is not found. @@ -440,7 +441,7 @@ and the given user data. @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. +@Returns: the found #GList element, or %NULL if it is not found. diff --git a/docs/reference/glib/tmpl/strings.sgml b/docs/reference/glib/tmpl/strings.sgml index 9dc55e2..58cf10c 100644 --- a/docs/reference/glib/tmpl/strings.sgml +++ b/docs/reference/glib/tmpl/strings.sgml @@ -22,10 +22,10 @@ The #GString struct contains the public fields of a #GString. The str field points to the character data. It may move as text is added. The len field contains the length of the string, -not including the terminating null character. +not including the terminating nul character. -The str field is zero-terminated and so can be used as an ordinary C +The str field is nul-terminated and so can be used as an ordinary C string. But it may be moved when text is appended or inserted into the string. @@ -49,14 +49,14 @@ Creates a new #GString with @len bytes of the @init buffer. Because a length is provided, @init need not be nul-terminated, and can contain embedded nul bytes. -@init: initial contents of string -@len: length of @init to use -@Returns: a new #GString +@init: initial contents of string. +@len: length of @init to use. +@Returns: a new #GString. -Creates a new GString, with enough space for @dfl_size characters. +Creates a new #GString, with enough space for @dfl_size characters. This is useful if you are going to add a lot of text to the string and don't want it to be reallocated too often. @@ -68,7 +68,7 @@ don't want it to be reallocated too often. Copies the characters from one #GString into another, destroying any previous -contents. It is rather like the standard strcpy() function, except that +contents. It is rather like the standard strcpy() function, except that you do not have to worry about having enough space to copy the string. @@ -81,8 +81,8 @@ you do not have to worry about having enough space to copy the string. Writes a formatted string into a #GString. This is similar to the standard sprintf() function, -except that the GString buffer automatically expands to contain the results. -The previous contents of the GString are destroyed. +except that the #GString buffer automatically expands to contain the results. +The previous contents of the #GString are destroyed. @@ -96,7 +96,7 @@ documentation. Appends a formatted string onto the end of a #GString. This function is is similar to g_string_sprintf() except that -the text is appended to the GString. +the text is appended to the #GString. @@ -108,22 +108,29 @@ documentation. - +Writes a formatted string into a #GString. +This is similar to the standard sprintf() function, +except that the #GString buffer automatically expands to contain the results. +The previous contents of the #GString are destroyed. -@string: -@format: -@Varargs: +@string: a #GString. +@format: the string format. See the sprintf() +documentation. +@Varargs: the parameters to insert into the format string. - +Appends a formatted string onto the end of a #GString. +This function is is similar to g_string_sprintf() except that +the text is appended to the #GString. -@string: -@format: -@Varargs: +@string: a #GString. +@format: the string format. See the sprintf() +documentation. +@Varargs: the parameters to insert into the format string. @@ -162,10 +169,10 @@ Appends @len bytes of @val to @string. Because @len is provided, @val may contain embedded nuls and need not be nul-terminated. -@string: a #GString -@val: bytes to append -@len: number of bytes of @val to use -@Returns: the #GString +@string: a #GString. +@val: bytes to append. +@len: number of bytes of @val to use. +@Returns: the #GString. @@ -204,10 +211,10 @@ Prepends @len bytes of @val to @string. Because @len is provided, @val may contain embedded nuls and need not be nul-terminated. -@string: a #GString -@val: bytes to prepend -@len: number of bytes in @val to prepend -@Returns: the #GString passed in +@string: a #GString. +@val: bytes to prepend. +@len: number of bytes in @val to prepend. +@Returns: the #GString passed in. @@ -249,11 +256,11 @@ Inserts @len bytes of @val into @string at @pos. Because @len is provided, @val may contain embedded nuls and need not be nul-terminated. If @pos is -1, bytes are inserted at the end of the string. -@string: a #GString -@pos: position in @string where insertion should happen, or -1 for at the end -@val: bytes to insert -@len: number of bytes of @val to insert -@Returns: the #GString +@string: a #GString. +@pos: position in @string where insertion should happen, or -1 for at the end. +@val: bytes to insert. +@len: number of bytes of @val to insert. +@Returns: the #GString. @@ -292,12 +299,11 @@ Cuts off the end of the GString, leaving the first @len characters. Frees the memory allocated for the #GString. -If free_segment is TRUE it also frees the character data. +If @free_segment is %TRUE it also frees the character data. @string: a #GString. -@free_segment: if TRUE the actual character data is freed as well. -@Returns: +@free_segment: if %TRUE the actual character data is freed as well. @@ -323,8 +329,8 @@ Converts a #GString to lower case. Creates a hash code for @str; for use with #GHashTable. -@str: a string to hash -@Returns: hash code for @str +@str: a string to hash. +@Returns: hash code for @str. @@ -333,8 +339,8 @@ Compares two strings for equality, returning %TRUE if they are equal. For use with #GHashTable. -@v: a #GString -@v2: another #GString -@Returns: %TRUE if they strings are the same length and contain the same bytes +@v: a #GString. +@v2: another #GString. +@Returns: %TRUE if they strings are the same length and contain the same bytes. diff --git a/docs/reference/glib/tmpl/warnings.sgml b/docs/reference/glib/tmpl/warnings.sgml index edd9ab2..2ecbed3 100644 --- a/docs/reference/glib/tmpl/warnings.sgml +++ b/docs/reference/glib/tmpl/warnings.sgml @@ -85,7 +85,7 @@ widget or a log file for example. Returns from the current function if the expression is not true. -If the expression evaluates to FALSE, a critical message is logged and +If the expression evaluates to %FALSE, a critical message is logged and the function returns. This can only be used in functions which do not return a value. @@ -97,7 +97,7 @@ a value. Returns from the current function, returning the value @val, if the expression is not true. -If the expression evaluates to FALSE, a critical message is logged and +If the expression evaluates to %FALSE, a critical message is logged and @val is returned. @@ -108,17 +108,18 @@ true. - +Logs a critical message and returns from the current function. +This can only be used in functions which do not return a value. - +Logs a critical message and returns @val. -@val: +@val: the value to return from the current function. @@ -129,7 +130,7 @@ is logged and the application is terminated. The macro can be turned off in final releases of code by defining -G_DISABLE_ASSERT when compiling the application. +#G_DISABLE_ASSERT when compiling the application. @expr: the expression to check. @@ -142,54 +143,54 @@ If it is reached, an error message is logged and the application is terminated. The macro can be turned off in final releases of code by defining -G_DISABLE_ASSERT when compiling the application. +#G_DISABLE_ASSERT when compiling the application. -Prompts the user with "[E]xit, [H]alt, show [S]tack trace or [P]roceed". +Prompts the user with [E]xit, [H]alt, show [S]tack trace or [P]roceed. This function is intended to be used for debugging use only. FIXME: How do you set it up? -If Exit is selected, the application terminates with a call to +If [E]xit is selected, the application terminates with a call to _exit(0). -If Halt is selected, the application enters an infinite loop. +If [H]alt is selected, the application enters an infinite loop. The infinite loop can only be stopped by killing the application, -or by setting glib_on_error_halt to FALSE (possibly via a debugger). +or by setting #glib_on_error_halt to %FALSE (possibly via a debugger). -If Stack trace is selected, g_on_error_stack_trace() is called. This -invokes gdb, which attaches to the current process and shows a stack trace. +If [S]tack trace is selected, g_on_error_stack_trace() is called. This +invokes gdb, which attaches to the current process and shows a stack trace. The prompt is then shown again. -If Proceed is selected, the function returns. +If [P]roceed is selected, the function returns. This function may cause different actions on non-unix platforms. -@prg_name: the program name, needed by gdb for the [S]tack trace option. -If @prg_name is NULL, g_get_prgname() is called to get the program name +@prg_name: the program name, needed by gdb for the [S]tack trace option. +If @prg_name is %NULL, g_get_prgname() is called to get the program name (which will work correctly if gdk_init() or gtk_init() has been called). -Invokes gdb, which attaches to the current process and shows a stack trace. +Invokes gdb, which attaches to the current process and shows a stack trace. Called by g_on_error_query() when the [S]tack trace option is selected. This function may cause different actions on non-unix platforms. -@prg_name: the program name, needed by gdb for the [S]tack trace option. -If @prg_name is NULL, g_get_prgname() is called to get the program name +@prg_name: the program name, needed by gdb for the [S]tack trace option. +If @prg_name is %NULL, g_get_prgname() is called to get the program name (which will work correctly if gdk_init() or gtk_init() has been called). -- 2.7.4