Commit 42d45541 authored by Matthias Clasen's avatar Matthias Clasen

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.
parent 5ce4dc18
2001-09-27 Matthias Clasen <matthiasc@poet.de>
* 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 <matthiasc@poet.de>
* glib/glib-sections.txt: Add g_mem_is_system_malloc.
......
......@@ -10,6 +10,7 @@
<!entity glib-Error-Reporting SYSTEM "sgml/error_reporting.sgml">
<!entity glib-Warnings-and-Assertions SYSTEM "sgml/warnings.sgml">
<!entity glib-Message-Logging SYSTEM "sgml/messages.sgml">
<!entity glib-Pattern-Matching SYSTEM "sgml/patterns.sgml">
<!entity glib-Timers SYSTEM "sgml/timers.sgml">
<!entity glib-String-Utility-Functions SYSTEM "sgml/string_utils.sgml">
<!entity glib-Character-Set-Conversion SYSTEM "sgml/conversions.sgml">
......@@ -97,6 +98,7 @@
&glib-Spawn;
&glib-Fileutils;
&glib-Shell;
&glib-Pattern-Matching;
&glib-Markup;
&glib-Windows-Compatability-Functions;
</chapter>
......
......@@ -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().
</para>
<!-- ##### SECTION See_Also ##### -->
......@@ -55,7 +57,7 @@ Creates a new #GCompletion.
</para>
@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.
<!-- ##### FUNCTION g_completion_set_compare ##### -->
<para>
Sets the function to use for string comparisons. The default
string comparison function is <function>strncmp()</function>.
</para>
@cmp:
@strncmp_func:
@cmp: a #GCompletion.
@strncmp_func: the string comparison function.
<!-- ##### USER_FUNCTION GCompletionStrncmpFunc ##### -->
<para>
Specifies the type of the function passed to g_completion_set_compare().
This is used when you use strings as #GCompletion items.
</para>
@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.
<!-- ##### FUNCTION g_completion_free ##### -->
<para>
Frees all memory used by the #GCompletion.
......
......@@ -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.
</para>
<para>
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.
</para>
<para>
To add elements, use g_list_append(), g_list_prepend(), g_list_insert()
......@@ -143,13 +143,14 @@ to the end of the list.
<!-- ##### FUNCTION g_list_insert_before ##### -->
<para>
Inserts a new element into the list before the given position.
</para>
@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.
<!-- ##### FUNCTION g_list_insert_sorted ##### -->
......@@ -181,7 +182,7 @@ If none of the elements contain the data, the #GList is unchanged.
<!-- ##### FUNCTION g_list_remove_link ##### -->
<para>
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.
</para>
......@@ -195,9 +196,9 @@ self-contained list with one element.
Deletes the node @link from @list.
</para>
@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.
<!-- ##### FUNCTION g_list_remove_all ##### -->
......@@ -207,9 +208,9 @@ head of the list. Contrast with g_list_remove() which removes only
the first node matching the given data.
</para>
@list: a #GList
@data: data to remove
@Returns: new head of @list
@list: a #GList.
@data: data to remove.
@Returns: new head of @list.
<!-- ##### FUNCTION g_list_free ##### -->
......@@ -224,7 +225,7 @@ first.
</para>
</note>
@list:
@list: a #GList.
<!-- ##### FUNCTION g_list_alloc ##### -->
......@@ -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.
</para>
@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.
<!-- ##### USER_FUNCTION GCompareFunc ##### -->
......@@ -354,7 +355,7 @@ Gets the first element in a #GList.
</para>
@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.
<!-- ##### FUNCTION g_list_last ##### -->
......@@ -363,7 +364,7 @@ Gets the last element in a #GList.
</para>
@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.
</para>
@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.
<!-- ##### MACRO g_list_next ##### -->
......@@ -382,7 +383,7 @@ A convenience macro to gets the next element in a #GList.
</para>
@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.
<!-- ##### FUNCTION g_list_nth ##### -->
......@@ -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.
<!-- ##### FUNCTION g_list_nth_data ##### -->
......@@ -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.
<!-- ##### FUNCTION g_list_nth_prev ##### -->
<para>
Gets the element @n places before @list.
</para>
@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.
<!-- ##### FUNCTION g_list_find ##### -->
......@@ -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.
<!-- ##### FUNCTION g_list_find_custom ##### -->
......@@ -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.
<!-- ##### FUNCTION g_list_position ##### -->
......
......@@ -22,10 +22,10 @@ The #GString struct contains the public fields of a #GString.
The <structfield>str</structfield> field points to the character data.
It may move as text is added.
The <structfield>len</structfield> field contains the length of the string,
not including the terminating null character.
not including the terminating nul character.
</para>
<para>
The str field is zero-terminated and so can be used as an ordinary C
The <structfield>str</structfield> 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.
</para>
......@@ -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.
</para>
@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.
<!-- ##### FUNCTION g_string_sized_new ##### -->
<para>
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.
</para>
......@@ -68,7 +68,7 @@ don't want it to be reallocated too often.
<!-- ##### FUNCTION g_string_assign ##### -->
<para>
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 <function>strcpy()</function> function, except that
you do not have to worry about having enough space to copy the string.
</para>
......@@ -81,8 +81,8 @@ you do not have to worry about having enough space to copy the string.
<para>
Writes a formatted string into a #GString.
This is similar to the standard <function>sprintf()</function> 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.
</para>
<!-- # Unused Parameters # -->
......@@ -96,7 +96,7 @@ documentation.
<para>
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.
</para>
<!-- # Unused Parameters # -->
......@@ -108,22 +108,29 @@ documentation.
<!-- ##### FUNCTION g_string_printf ##### -->
<para>
Writes a formatted string into a #GString.
This is similar to the standard <function>sprintf()</function> function,
except that the #GString buffer automatically expands to contain the results.
The previous contents of the #GString are destroyed.
</para>
@string:
@format:
@Varargs:
@string: a #GString.
@format: the string format. See the <function>sprintf()</function>
documentation.
@Varargs: the parameters to insert into the format string.
<!-- ##### FUNCTION g_string_printfa ##### -->
<para>
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.
</para>
@string:
@format:
@Varargs:
@string: a #GString.
@format: the string format. See the <function>sprintf()</function>
documentation.
@Varargs: the parameters to insert into the format string.
<!-- ##### FUNCTION g_string_append ##### -->
......@@ -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.
</para>
@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.
<!-- ##### FUNCTION g_string_prepend ##### -->
......@@ -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.
</para>
@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.
<!-- ##### FUNCTION g_string_insert ##### -->
......@@ -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.
</para>
@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.
<!-- ##### FUNCTION g_string_erase ##### -->
......@@ -292,12 +299,11 @@ Cuts off the end of the GString, leaving the first @len characters.
<!-- ##### FUNCTION g_string_free ##### -->
<para>
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.
</para>
@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.
<!-- ##### FUNCTION g_string_up ##### -->
......@@ -323,8 +329,8 @@ Converts a #GString to lower case.
Creates a hash code for @str; for use with #GHashTable.
</para>
@str: a string to hash
@Returns: hash code for @str
@str: a string to hash.
@Returns: hash code for @str.
<!-- ##### FUNCTION g_string_equal ##### -->
......@@ -333,8 +339,8 @@ Compares two strings for equality, returning %TRUE if they are equal.
For use with #GHashTable.
</para>
@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.
......@@ -85,7 +85,7 @@ widget or a log file for example.
<!-- ##### MACRO g_return_if_fail ##### -->
<para>
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.
</para>
......@@ -97,7 +97,7 @@ a value.
<para>
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.
</para>
......@@ -108,17 +108,18 @@ true.
<!-- ##### MACRO g_return_if_reached ##### -->
<para>
Logs a critical message and returns from the current function.
This can only be used in functions which do not return a value.
</para>
<!-- ##### MACRO g_return_val_if_reached ##### -->
<para>
Logs a critical message and returns @val.
</para>
@val:
@val: the value to return from the current function.
<!-- ##### MACRO g_assert ##### -->
......@@ -129,7 +130,7 @@ is logged and the application is terminated.
</para>
<para>
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.
</para>
@expr: the expression to check.
......@@ -142,54 +143,54 @@ If it is reached, an error message is logged and the application is terminated.
</para>
<para>
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.
</para>
<!-- ##### FUNCTION g_on_error_query ##### -->
<para>
Prompts the user with "[E]xit, [H]alt, show [S]tack trace or [P]roceed".
Prompts the user with <computeroutput>[E]xit, [H]alt, show [S]tack trace or [P]roceed</computeroutput>.
This function is intended to be used for debugging use only.
FIXME: How do you set it up?
</para>
<para>
If Exit is selected, the application terminates with a call to
If [E]xit is selected, the application terminates with a call to
<function>_exit(0)</function>.
</para>
<para>
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).
</para>
<para>
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 <command>gdb</command>, which attaches to the current process and shows a stack trace.
The prompt is then shown again.
</para>
<para>
If Proceed is selected, the function returns.
If [P]roceed is selected, the function returns.
</para>
<para>
This function may cause different actions on non-unix platforms.
</para>
@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 <command>gdb</command> 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).
<!-- ##### FUNCTION g_on_error_stack_trace ##### -->
<para>
Invokes gdb, which attaches to the current process and shows a stack trace.
Invokes <command>gdb</command>, 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.
</para>
<para>
This function may cause different actions on non-unix platforms.
</para>
@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 <command>gdb</command> 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).
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment