Mercurial > pidgin
changeset 20751:fe77cc691f78
Some doxygen stuff.
| author | Sadrul Habib Chowdhury <imadil@gmail.com> |
|---|---|
| date | Tue, 02 Oct 2007 04:22:26 +0000 |
| parents | 0ee0cad488b4 |
| children | e92c9987ba0d |
| files | finch/libgnt/gntbindable.h finch/libgnt/gntbutton.h finch/libgnt/gntcheckbox.h finch/libgnt/gntclipboard.c finch/libgnt/gntclipboard.h finch/libgnt/gntcolors.h finch/libgnt/gntcombobox.h finch/libgnt/gntentry.h finch/libgnt/gnttree.c |
| diffstat | 9 files changed, 141 insertions(+), 124 deletions(-) [+] |
line wrap: on
line diff
--- a/finch/libgnt/gntbindable.h Tue Oct 02 03:46:43 2007 +0000 +++ b/finch/libgnt/gntbindable.h Tue Oct 02 04:22:26 2007 +0000 @@ -105,73 +105,75 @@ /*GntBindableAction *gnt_bindable_action_parse(const char *name);*/ /** - * - * @param action + * Free a bindable action. + * + * @param action The bindable action. */ void gnt_bindable_action_free(GntBindableAction *action); /** - * - * @param param + * Free a GntBindableActionParam. + * + * @param param The GntBindableActionParam to free. */ void gnt_bindable_action_param_free(GntBindableActionParam *param); /** - * - * @param klass - * @param name - * @param callback - * @param trigger + * Register a bindable action for a class. + * + * @param klass The class the binding is for. + * @param name The name of the binding. + * @param callback The callback for the binding. + * @param trigger The default trigger for the binding, or @c NULL, followed by a NULL-terminated + * list of default parameters. */ void gnt_bindable_class_register_action(GntBindableClass *klass, const char *name, GntBindableActionCallback callback, const char *trigger, ...); /** - * - * @param klass - * @param name - * @param trigger + * Register a key-binding to an existing action. + * + * @param klass The class the binding is for. + * @param name The name of the binding. + * @param trigger A new trigger for the binding, followed by a @c NULL-terminated list of parameters for the callback. */ void gnt_bindable_register_binding(GntBindableClass *klass, const char *name, const char *trigger, ...); /** - * - * @param bindable - * @param keys + * Perform an action from a keybinding. * - * @return + * @param bindable The bindable object. + * @param keys The key to trigger the action. + * + * @return @c TRUE if the action was performed successfully, @c FALSE otherwise. */ gboolean gnt_bindable_perform_action_key(GntBindable *bindable, const char *keys); /** - * - * @param bindable - * @param name + * Perform an action on a bindable object. * - * @return + * @param bindable The bindable object. + * @param name The action to perform, followed by a @c NULL-terminated list of parameters. + * + * @return @c TRUE if the action was performed successfully, @c FALSE otherwise. */ gboolean gnt_bindable_perform_action_named(GntBindable *bindable, const char *name, ...); /** -* Returns a GntTree populated with "key" -> "binding" for the widget. -*/ -/** -* -* @param widget -* -* @return -*/ + * Returns a GntTree populated with "key" -> "binding" for the widget. + * + * @param widget The object to list the bindings for. + * + * @return The GntTree. + */ GntBindable * gnt_bindable_bindings_view(GntBindable *bind); /** - * - * Builds a window that list the key bindings for a GntBindable object. From this window a user can select a listing to rebind a new key for the given action. - * - */ -/** + * Builds a window that list the key bindings for a GntBindable object. + * From this window a user can select a listing to rebind a new key for the given action. * - * @param bindable + * @param bindable The object to list the bindings for. * - * @return + * @return @c TRUE */ gboolean gnt_bindable_build_help_window(GntBindable *bindable);
--- a/finch/libgnt/gntbutton.h Tue Oct 02 03:46:43 2007 +0000 +++ b/finch/libgnt/gntbutton.h Tue Oct 02 04:22:26 2007 +0000 @@ -73,17 +73,16 @@ G_BEGIN_DECLS /** - * - * - * @return + * @return GType for Gntbutton */ GType gnt_button_get_gtype(void); /** - * - * @param text + * Create a new button. * - * @return + * @param text The text for the button. + * + * @return The newly created button. */ GntWidget * gnt_button_new(const char *text);
--- a/finch/libgnt/gntcheckbox.h Tue Oct 02 03:46:43 2007 +0000 +++ b/finch/libgnt/gntcheckbox.h Tue Oct 02 04:22:26 2007 +0000 @@ -68,32 +68,33 @@ G_BEGIN_DECLS /** - * - * - * @return + * @return GType for GntCheckBox */ GType gnt_check_box_get_gtype(void); /** - * - * @param text + * Create a new checkbox. * - * @return + * @param text The text for the checkbox. + * + * @return The newly created checkbox. */ GntWidget * gnt_check_box_new(const char *text); /** - * - * @param box - * @param set + * Set whether the checkbox should be checked or not. + * + * @param box The checkbox. + * @param set @c TRUE if the checkbox should be selected, @c FALSE otherwise. */ void gnt_check_box_set_checked(GntCheckBox *box, gboolean set); /** - * - * @param box + * Return the checked state of the checkbox. * - * @return + * @param box The checkbox. + * + * @return @c TRUE if the checkbox is selected, @c FALSE otherwise. */ gboolean gnt_check_box_get_checked(GntCheckBox *box);
--- a/finch/libgnt/gntclipboard.c Tue Oct 02 03:46:43 2007 +0000 +++ b/finch/libgnt/gntclipboard.c Tue Oct 02 04:22:26 2007 +0000 @@ -48,7 +48,7 @@ *****************************************************************************/ void -gnt_clipboard_set_string(GntClipboard *clipboard, gchar *string) +gnt_clipboard_set_string(GntClipboard *clipboard, const gchar *string) { g_free(clipboard->string); clipboard->string = g_strdup(string);
--- a/finch/libgnt/gntclipboard.h Tue Oct 02 03:46:43 2007 +0000 +++ b/finch/libgnt/gntclipboard.h Tue Oct 02 04:22:26 2007 +0000 @@ -60,26 +60,27 @@ G_BEGIN_DECLS /** - * - * - * @return + * @return GType for GntClipboard. */ GType gnt_clipboard_get_gtype(void); /** - * - * @param clip + * Get the current text from the clipboard. * - * @return + * @param clip The clipboard. + * + * @return A copy of the string in the clipboard. The caller should free the + * returned value. */ gchar * gnt_clipboard_get_string(GntClipboard *clip); /** - * - * @param clip - * @param string + * Set the text in the clipboard. + * + * @param clip The clipboard. + * @param string New string for the clipboard. */ -void gnt_clipboard_set_string(GntClipboard *clip, gchar *string); +void gnt_clipboard_set_string(GntClipboard *clip, const gchar *string); G_END_DECLS
--- a/finch/libgnt/gntcolors.h Tue Oct 02 03:46:43 2007 +0000 +++ b/finch/libgnt/gntcolors.h Tue Oct 02 04:22:26 2007 +0000 @@ -29,6 +29,9 @@ #include <glib.h> +/** + * Different classes of colors. + */ typedef enum { GNT_COLOR_NORMAL = 1, @@ -58,27 +61,28 @@ GNT_TOTAL_COLORS }; -/* populate some default colors */ /** - * + * Initialize the colors. */ void gnt_init_colors(void); /** - * + * Uninitialize the colors. */ void gnt_uninit_colors(void); #if GLIB_CHECK_VERSION(2,6,0) /** - * - * @param kfile + * Parse color information from a file. + * + * @param kfile The file containing color information. */ void gnt_colors_parse(GKeyFile *kfile); /** - * - * @param kfile + * Parse color-pair information from a file. + * + * @param kfile The file containing the color-pair information. */ void gnt_color_pairs_parse(GKeyFile *kfile);
--- a/finch/libgnt/gntcombobox.h Tue Oct 02 03:46:43 2007 +0000 +++ b/finch/libgnt/gntcombobox.h Tue Oct 02 04:22:26 2007 +0000 @@ -69,15 +69,11 @@ G_BEGIN_DECLS /** - * - * Get the GType for GntComboBox - * - * @return + * @return Get the GType for GntComboBox */ GType gnt_combo_box_get_gtype(void); /** - * * Create a new GntComboBox * * @return A new GntComboBox @@ -85,7 +81,6 @@ GntWidget * gnt_combo_box_new(void); /** - * * Add an entry * * @param box The GntComboBox @@ -95,7 +90,6 @@ void gnt_combo_box_add_data(GntComboBox *box, gpointer key, const char *text); /** - * * Remove an entry * * @param box The GntComboBox @@ -104,7 +98,6 @@ void gnt_combo_box_remove(GntComboBox *box, gpointer key); /** - * * Remove all entries * * @param box The GntComboBox @@ -112,7 +105,6 @@ void gnt_combo_box_remove_all(GntComboBox *box); /** - * * Get the data that is currently selected * * @param box The GntComboBox @@ -122,7 +114,6 @@ gpointer gnt_combo_box_get_selected_data(GntComboBox *box); /** - * * Set the current selection to a specific entry * * @param box The GntComboBox
--- a/finch/libgnt/gntentry.h Tue Oct 02 03:46:43 2007 +0000 +++ b/finch/libgnt/gntentry.h Tue Oct 02 04:22:26 2007 +0000 @@ -100,95 +100,115 @@ G_BEGIN_DECLS /** - * - * - * @return + * @return GType for GntEntry. */ GType gnt_entry_get_gtype(void); /** - * - * @param text + * Create a new GntEntry. * - * @return + * @param text The text in the new entry box. + * + * @return The newly created entry box. */ GntWidget * gnt_entry_new(const char *text); /** - * - * @param entry - * @param max + * Set the maximum length of the text in the entry box. + * + * @param entry The entry box. + * @param max The maximum length for text. A value of 0 means infinite length. */ void gnt_entry_set_max(GntEntry *entry, int max); /** - * - * @param entry - * @param text + * Set the text in an entry box. + * + * @param entry The entry box. + * @param text The text to set in the box. */ void gnt_entry_set_text(GntEntry *entry, const char *text); /** - * - * @param entry - * @param flag + * Set flags an entry box. + * + * @param entry The entry box. + * @param flag The flags to set for the entry box. */ void gnt_entry_set_flag(GntEntry *entry, GntEntryFlag flag); +/** + * Get the text in an entry box. + * + * @param entry The entry box. + * + * @return The current text in the entry box. + */ const char *gnt_entry_get_text(GntEntry *entry); /** - * - * @param entry + * Clear the text in the entry box. + * + * @param entry The entry box. */ void gnt_entry_clear(GntEntry *entry); /** - * - * @param entry - * @param set + * Set whether the text in the entry box should be masked for display. + * + * @param entry The entry box. + * @param set @c TRUE if the text should be masked, @c FALSE otherwise. */ void gnt_entry_set_masked(GntEntry *entry, gboolean set); /** - * - * @param entry - * @param text + * Add a text to the history list for the text. The history length for the + * entry box needs to be set first by gnt_entry_set_history_length. + * + * @param entry The entry box. + * @param text A new entry for the history list. */ void gnt_entry_add_to_history(GntEntry *entry, const char *text); /** - * - * @param entry - * @param num + * Set the length of history for the entry box. + * + * @param entry The entry box. + * @param num The maximum length of the history. */ void gnt_entry_set_history_length(GntEntry *entry, int num); /** - * - * @param entry - * @param word + * Set whether the suggestions are for the entire entry box, or for each + * individual word in the entry box. + * + * @param entry The entry box. + * @param word @c TRUE if the suggestions are for individual words, @c FALSE otherwise. */ void gnt_entry_set_word_suggest(GntEntry *entry, gboolean word); /** - * - * @param entry - * @param always + * Set whether to always display the suggestions list, or only when the + * tab-completion key is pressed (the TAB key, by default). + * + * @param entry The entry box. + * @param always @c TRUE if the suggestion list should always be displayed. */ void gnt_entry_set_always_suggest(GntEntry *entry, gboolean always); /** - * - * @param entry - * @param text + * Add an item to the suggestion list. + * + * @param entry The entry box. + * @param text An item to add to the suggestion list. */ void gnt_entry_add_suggest(GntEntry *entry, const char *text); /** - * - * @param entry - * @param text + * Remove an entry from the suggestion list. + * + * @param entry The entry box. + * @param text The item to remove from the suggestion list. */ void gnt_entry_remove_suggest(GntEntry *entry, const char *text);
--- a/finch/libgnt/gnttree.c Tue Oct 02 03:46:43 2007 +0000 +++ b/finch/libgnt/gnttree.c Tue Oct 02 04:22:26 2007 +0000 @@ -1265,8 +1265,10 @@ { GntTreeRow *pr = NULL; + row->tree = tree; + row->key = key; + row->data = NULL; g_hash_table_replace(tree->hash, key, row); - row->tree = tree; if (bigbro == NULL && tree->priv->compare) { @@ -1327,9 +1329,6 @@ } } - row->key = key; - row->data = NULL; - redraw_tree(tree); return row;