From 5ee096636b3e603863e0935c2e7ff107b4d72f63 Mon Sep 17 00:00:00 2001 From: Ryan Lortie Date: Sun, 31 Jan 2010 00:03:33 -0500 Subject: [PATCH] GCompletion: move docs from tmpl to .c --- docs/reference/glib/tmpl/.gitignore | 1 + docs/reference/glib/tmpl/completion.sgml | 158 ------------------------------- glib/gcompletion.c | 122 ++++++++++++++++++++++++ 3 files changed, 123 insertions(+), 158 deletions(-) delete mode 100644 docs/reference/glib/tmpl/completion.sgml diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore index 0411303..307edca 100644 --- a/docs/reference/glib/tmpl/.gitignore +++ b/docs/reference/glib/tmpl/.gitignore @@ -1,5 +1,6 @@ allocators.sgml base64.sgml +completion.sgml datasets.sgml datalist.sgml ghostutils.sgml diff --git a/docs/reference/glib/tmpl/completion.sgml b/docs/reference/glib/tmpl/completion.sgml deleted file mode 100644 index efa26fa..0000000 --- a/docs/reference/glib/tmpl/completion.sgml +++ /dev/null @@ -1,158 +0,0 @@ - -Automatic String Completion - - -support for automatic completion using a group of target strings - - - -#GCompletion provides support for automatic completion of a string using -any group of target strings. It is typically used for file name completion -as is common in many UNIX shells. - - -A #GCompletion is created using g_completion_new(). -Target items are added and removed with -g_completion_add_items(), g_completion_remove_items() and -g_completion_clear_items(). -A completion attempt is requested with g_completion_complete() or -g_completion_complete_utf8(). -When no longer needed, the #GCompletion is freed with g_completion_free(). - - -Items in the completion can be simple strings (e.g. filenames), -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(). - - - - - - - - - - - - -The data structure used for automatic completion. - - -@items: list of target items (strings or data structures). -@func: function which is called to get the string associated with a target - item. It is %NULL if the target items are strings. -@prefix: the last prefix passed to g_completion_complete() or - g_completion_complete_utf8(). -@cache: the list of items which begin with @prefix. -@strncmp_func: The function to use when comparing strings. - Use g_completion_set_compare() to modify this function. - - - -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 -#GCompletion items. -@Returns: the new #GCompletion. - - - - -Specifies the type of the function passed to g_completion_new(). -It should return the string corresponding to the given target item. -This is used when you use data structures as #GCompletion items. - - -@Param1: the completion item. -@Returns: the string corresponding to the item. - - - - -Adds items to the #GCompletion. - - -@cmp: the #GCompletion. -@items: the list of items to add. - - - - -Removes items from a #GCompletion. - - -@cmp: the #GCompletion. -@items: the items to remove. - - - - -Removes all items from the #GCompletion. - - -@cmp: the #GCompletion. - - - - -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. -This string should be freed when no longer needed. -@Returns: the list of items whose strings begin with @prefix. This should -not be changed. - - - - - - - -@cmp: -@prefix: -@new_prefix: -@Returns: - - - - -Sets the function to use for string comparisons. The default -string comparison function is strncmp(). - - -@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: 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. - - -@cmp: the #GCompletion. - - diff --git a/glib/gcompletion.c b/glib/gcompletion.c index 5d26078..904f850 100644 --- a/glib/gcompletion.c +++ b/glib/gcompletion.c @@ -35,9 +35,82 @@ #include "glib.h" #include "galias.h" +/** + * SECTION: completion + * @title: Automatic String Completion + * @short_description: support for automatic completion using a group + * of target strings + * + * #GCompletion provides support for automatic completion of a string + * using any group of target strings. It is typically used for file + * name completion as is common in many UNIX shells. + * + * A #GCompletion is created using g_completion_new(). Target items are + * added and removed with g_completion_add_items(), + * g_completion_remove_items() and g_completion_clear_items(). A + * completion attempt is requested with g_completion_complete() or + * g_completion_complete_utf8(). When no longer needed, the + * #GCompletion is freed with g_completion_free(). + * + * Items in the completion can be simple strings (e.g. filenames), 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(). + **/ + +/** + * GCompletion: + * @items: list of target items (strings or data structures). + * @func: function which is called to get the string associated with a + * target item. It is %NULL if the target items are strings. + * @prefix: the last prefix passed to g_completion_complete() or + * g_completion_complete_utf8(). + * @cache: the list of items which begin with @prefix. + * @strncmp_func: The function to use when comparing strings. Use + * g_completion_set_compare() to modify this function. + * + * The data structure used for automatic completion. + **/ + +/** + * GCompletionFunc: + * @Param1: the completion item. + * @Returns: the string corresponding to the item. + * + * Specifies the type of the function passed to g_completion_new(). It + * should return the string corresponding to the given target item. + * This is used when you use data structures as #GCompletion items. + **/ + +/** + * GCompletionStrncmpFunc: + * @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. + * + * Specifies the type of the function passed to + * g_completion_set_compare(). This is used when you use strings as + * #GCompletion items. + **/ + static void completion_check_cache (GCompletion* cmp, gchar** new_prefix); +/** + * g_completion_new: + * @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 #GCompletion items. + * @Returns: the new #GCompletion. + * + * Creates a new #GCompletion. + **/ GCompletion* g_completion_new (GCompletionFunc func) { @@ -53,6 +126,13 @@ g_completion_new (GCompletionFunc func) return gcomp; } +/** + * g_completion_add_items: + * @cmp: the #GCompletion. + * @items: the list of items to add. + * + * Adds items to the #GCompletion. + **/ void g_completion_add_items (GCompletion* cmp, GList* items) @@ -82,6 +162,13 @@ g_completion_add_items (GCompletion* cmp, } } +/** + * g_completion_remove_items: + * @cmp: the #GCompletion. + * @items: the items to remove. + * + * Removes items from a #GCompletion. + **/ void g_completion_remove_items (GCompletion* cmp, GList* items) @@ -105,6 +192,12 @@ g_completion_remove_items (GCompletion* cmp, } } +/** + * g_completion_clear_items: + * @cmp: the #GCompletion. + * + * Removes all items from the #GCompletion. + **/ void g_completion_clear_items (GCompletion* cmp) { @@ -213,6 +306,21 @@ g_completion_complete_utf8 (GCompletion *cmp, return list; } +/** + * g_completion_complete: + * @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. This string should be freed + * when no longer needed. + * @Returns: the list of items whose strings begin with @prefix. This + * should not be changed. + * + * Attempts to complete the string @prefix using the #GCompletion + * target items. + **/ GList* g_completion_complete (GCompletion* cmp, const gchar* prefix, @@ -275,6 +383,12 @@ g_completion_complete (GCompletion* cmp, return *prefix ? cmp->cache : cmp->items; } +/** + * g_completion_free: + * @cmp: the #GCompletion. + * + * Frees all memory used by the #GCompletion. + **/ void g_completion_free (GCompletion* cmp) { @@ -284,6 +398,14 @@ g_completion_free (GCompletion* cmp) g_free (cmp); } +/** + * g_completion_set_compare: + * @cmp: a #GCompletion. + * @strncmp_func: the string comparison function. + * + * Sets the function to use for string comparisons. The default string + * comparison function is strncmp(). + **/ void g_completion_set_compare(GCompletion *cmp, GCompletionStrncmpFunc strncmp_func) -- 2.7.4