[seahorse/gtk-doc] Add annotations and harmonize function defs and implementations

[Adam Schreiber <sadam src gnome org>]

commit 9c39c42867c55a1484161564eeb0e51567ebd14e
Author: Adam Schreiber <sadam gnome org>
Date:   Sun May 3 22:13:13 2009 -0400

    Add annotations and harmonize function defs and implementations
---
 libcryptui/cryptui-key-combo.c |   40 +++++++-------
 libcryptui/cryptui-key-combo.h |    6 +-
 libcryptui/cryptui-key-list.c  |  113 +++++++++++++++++++++++++++++++++------
 libcryptui/cryptui-key-list.h  |   14 +++---
 4 files changed, 125 insertions(+), 48 deletions(-)

diff --git a/libcryptui/cryptui-key-combo.c b/libcryptui/cryptui-key-combo.c
index 9903a78..cda189a 100644
--- a/libcryptui/cryptui-key-combo.c
+++ b/libcryptui/cryptui-key-combo.c
@@ -51,9 +51,9 @@ is_row_separator (GtkTreeModel *model, GtkTreeIter *iter, gpointer data)
 GtkComboBox*
 cryptui_key_combo_new (CryptUIKeyStore *ckstore)
 {
-    GtkComboBox *combo = g_object_new (GTK_TYPE_COMBO_BOX, "model", ckstore, NULL);
-    cryptui_key_combo_setup (combo, ckstore);
-    return combo;
+    GtkComboBox *ckcombo = g_object_new (GTK_TYPE_COMBO_BOX, "model", ckstore, NULL);
+    cryptui_key_combo_setup (ckcombo, ckstore);
+    return ckcombo;
 }
 
 /**
@@ -83,48 +83,48 @@ cryptui_key_combo_setup (GtkComboBox *combo, CryptUIKeyStore *ckstore)
 
 /**
  * cryptui_key_combo_get_key_store:
- * @combo: a CryptUICombo
+ * @ckcombo: a CryptUICombo
  *
  * Gets the key store from a CryptUiCombo
  *
  * Returns: the key store
  */
 CryptUIKeyStore*
-cryptui_key_combo_get_key_store (GtkComboBox *combo)
+cryptui_key_combo_get_key_store (GtkComboBox *ckcombo)
 {
-    GtkTreeModel *model = gtk_combo_box_get_model (combo);
+    GtkTreeModel *model = gtk_combo_box_get_model (ckcombo);
     g_return_val_if_fail (CRYPTUI_KEY_STORE (model), NULL);
     return CRYPTUI_KEY_STORE (model);
 }
 
 /**
  * cryptui_key_combo_get_keyset:
- * @combo: a CryptUICombo
+ * @ckcombo: a CryptUICombo
  *
  * Gets the keyset stored in the combo's key store.
  *
  * Returns: a CryptuiKeyset
  */
 CryptUIKeyset*
-cryptui_key_combo_get_keyset (GtkComboBox *combo)
+cryptui_key_combo_get_keyset (GtkComboBox *ckcombo)
 {
-    CryptUIKeyStore *ckstore = cryptui_key_combo_get_key_store (combo);
+    CryptUIKeyStore *ckstore = cryptui_key_combo_get_key_store (ckcombo);
     return ckstore ? cryptui_key_store_get_keyset (ckstore) : NULL;
 }
 
 /**
  * cryptui_key_combo_set_key:
- * @combo: a CryptUICombo
+ * @ckcombo: a CryptUICombo
  * @key: a CryptUI Key
  *
- * Sets the combo's current selection to the indicated key
+ * Sets the combo's selection to the indicated key
  *
  * Returns: void
  */
 void
-cryptui_key_combo_set_key (GtkComboBox *combo, const gchar *key)
+cryptui_key_combo_set_key (GtkComboBox *ckcombo, const gchar *key)
 {
-    GtkTreeModel *model = gtk_combo_box_get_model (combo);
+    GtkTreeModel *model = gtk_combo_box_get_model (ckcombo);
     CryptUIKeyStore *ckstore;
     GtkTreeIter iter;
 
@@ -132,28 +132,28 @@ cryptui_key_combo_set_key (GtkComboBox *combo, const gchar *key)
     ckstore = CRYPTUI_KEY_STORE (model);
 
     if (cryptui_key_store_get_iter_from_key (ckstore, key, &iter))
-        gtk_combo_box_set_active_iter (combo, &iter);
+        gtk_combo_box_set_active_iter (ckcombo, &iter);
 }
 
 /**
  * cryptui_key_combo_get_key:
- * @combo: a CryptUICombo
+ * @ckcombo: a CryptUICombo
  *
- * Gets the currently selected key from the combo
+ * Gets the first selected key from the combo
  *
- * Returns: the currently selected key
+ * Returns: the first selected key
  */
 const gchar*
-cryptui_key_combo_get_key (GtkComboBox *combo)
+cryptui_key_combo_get_key (GtkComboBox *ckcombo)
 {
-    GtkTreeModel *model = gtk_combo_box_get_model (combo);
+    GtkTreeModel *model = gtk_combo_box_get_model (ckcombo);
     CryptUIKeyStore *ckstore;
     GtkTreeIter iter;
 
     g_return_val_if_fail (CRYPTUI_IS_KEY_STORE (model), NULL);
     ckstore = CRYPTUI_KEY_STORE (model);
 
-    if (gtk_combo_box_get_active_iter (combo, &iter))
+    if (gtk_combo_box_get_active_iter (ckcombo, &iter))
         return cryptui_key_store_get_key_from_iter (ckstore, &iter);
 
     return NULL;
diff --git a/libcryptui/cryptui-key-combo.h b/libcryptui/cryptui-key-combo.h
index a4c525b..238a0f8 100644
--- a/libcryptui/cryptui-key-combo.h
+++ b/libcryptui/cryptui-key-combo.h
@@ -38,11 +38,11 @@ GtkComboBox*      cryptui_key_combo_new             (CryptUIKeyStore *ckstore);
 void              cryptui_key_combo_setup           (GtkComboBox *combo,
                                                      CryptUIKeyStore *ckstore);
                                                      
-CryptUIKeyStore*  cryptui_key_combo_get_key_store   (GtkComboBox *combo);
+CryptUIKeyStore*  cryptui_key_combo_get_key_store   (GtkComboBox *ckcombo);
 
-CryptUIKeyset*    cryptui_key_combo_get_keyset      (GtkComboBox *combo);
+CryptUIKeyset*    cryptui_key_combo_get_keyset      (GtkComboBox *ckcombo);
 
-void              cryptui_key_combo_set_key         (GtkComboBox *combo,
+void              cryptui_key_combo_set_key         (GtkComboBox *ckcombo,
                                                      const gchar *key);
 
 const gchar*      cryptui_key_combo_get_key         (GtkComboBox *ckcombo);
diff --git a/libcryptui/cryptui-key-list.c b/libcryptui/cryptui-key-list.c
index 41bc0a5..153f2f3 100644
--- a/libcryptui/cryptui-key-list.c
+++ b/libcryptui/cryptui-key-list.c
@@ -75,14 +75,35 @@ row_activated (GtkTreeView *treeview, GtkTreePath *path, GtkTreeViewColumn *arg2
  * PUBLIC
  */
 
+/**
+ * cryptui_key_list_new:
+ * @ckstore: a CryptUIKeyStore containing keys to list
+ * @flags: CryptUIKeyFlags indicating which keys from the store to list
+ *
+ * Creates a new key list widget displaying keys from the key store that match
+ * the given flags.
+ *
+ * Returns: the new key list widget
+ */
 GtkTreeView*      
 cryptui_key_list_new (CryptUIKeyStore *ckstore, guint flags)
 {
-    GtkTreeView *view = GTK_TREE_VIEW (gtk_tree_view_new ());
-    cryptui_key_list_setup (view, ckstore, flags);
-    return view;
+    GtkTreeView *list = GTK_TREE_VIEW (gtk_tree_view_new ());
+    cryptui_key_list_setup (list, ckstore, flags);
+    return list;
 }
 
+/**
+ * cryptui_key_list_setup:
+ * @view: an existing tree view to be turned into a CryptUIKeyList
+ * @ckstore: a CryptUIKeyStore containing keys to list
+ * @flags: CryptUIKeyFlags indicating which keys from the store to list
+ *
+ * Changes an existing GtkTreeView into a CryptUIKeyList using the key store
+ * as the model and the filters the view based on the given flags.
+ *
+ * Returns: void
+ */
 void
 cryptui_key_list_setup (GtkTreeView *view, CryptUIKeyStore *ckstore,
                         guint flags)
@@ -135,6 +156,14 @@ cryptui_key_list_setup (GtkTreeView *view, CryptUIKeyStore *ckstore,
     gtk_widget_set_size_request (GTK_WIDGET (view), 500, 250);
 }
 
+/**
+ * cryptui_key_list_get_key_store:
+ * @list: a CryptUIKeyList
+ *
+ * Gets the CryptuiKeyStore used as a model by the CryptuiKeyList
+ *
+ * Returns: a CryptUIKeyList
+ */
 CryptUIKeyStore*
 cryptui_key_list_get_key_store (GtkTreeView *list)
 {
@@ -143,6 +172,14 @@ cryptui_key_list_get_key_store (GtkTreeView *list)
     return CRYPTUI_KEY_STORE (model);
 }
 
+/**
+ * cryptui_key_list_get_keyset:
+ * @list: a CryptUIKeyList
+ *
+ * Gets the keyset from the key store set as the model in the list
+ *
+ * Returns: a CryptUIKeyset
+ */
 CryptUIKeyset* 
 cryptui_key_list_get_keyset (GtkTreeView *list)
 {
@@ -150,57 +187,97 @@ cryptui_key_list_get_keyset (GtkTreeView *list)
     return ckstore ? cryptui_key_store_get_keyset (ckstore) : NULL;
 }
 
+/**
+ * cryptui_key_list_have_selected_keys:
+ * @list: a CryptUIKeyList
+ *
+ * Used to determine if any keys have been selected
+ *
+ * Returns: TRUE if keys have been selected, FALSE otherwise
+ */
 gboolean          
-cryptui_key_list_have_selected_keys (GtkTreeView *view)
+cryptui_key_list_have_selected_keys (GtkTreeView *list)
 {
     GtkTreeModel *model;
     
-    model = gtk_tree_view_get_model (view);
+    model = gtk_tree_view_get_model (list);
     g_return_val_if_fail (CRYPTUI_IS_KEY_STORE (model), FALSE);
     
-    return cryptui_key_store_have_selected_keys (CRYPTUI_KEY_STORE (model), view);
+    return cryptui_key_store_have_selected_keys (CRYPTUI_KEY_STORE (model), list);
 }
 
+/**
+ * cryptui_key_list_get_selected_keys:
+ * @list: a CryptUIKeyList
+ *
+ * Gets the kyes selected in the list
+ *
+ * Returns: a list of selected keys 
+ */
 GList*
-cryptui_key_list_get_selected_keys (GtkTreeView *view)
+cryptui_key_list_get_selected_keys (GtkTreeView *list)
 {
     GtkTreeModel *model;
     
-    model = gtk_tree_view_get_model (view);
+    model = gtk_tree_view_get_model (list);
     g_return_val_if_fail (CRYPTUI_IS_KEY_STORE (model), NULL);
     
-    return cryptui_key_store_get_selected_keys (CRYPTUI_KEY_STORE (model), view);
+    return cryptui_key_store_get_selected_keys (CRYPTUI_KEY_STORE (model), list);
 }
 
+/**
+ * cryptui_key_list_set_selected_keys:
+ * @list: a CryptUIKeyList
+ * @keys: a list of CryptUI keys
+ *
+ * Selects the given list of keys in the list
+ *
+ * Returns: void
+ */
 void
-cryptui_key_list_set_selected_keys (GtkTreeView *view, GList *keys)
+cryptui_key_list_set_selected_keys (GtkTreeView *list, GList *keys)
 {
     GtkTreeModel *model;
     
-    model = gtk_tree_view_get_model (view);
+    model = gtk_tree_view_get_model (list);
     g_return_if_fail (CRYPTUI_IS_KEY_STORE (model));
     
-    cryptui_key_store_set_selected_keys (CRYPTUI_KEY_STORE (model), view, keys);
+    cryptui_key_store_set_selected_keys (CRYPTUI_KEY_STORE (model), list, keys);
 }
 
+/**
+ * cryptui_key_list_get_selected_key:
+ * @list: a CryptUIKeyList
+ *
+ * Returns: the selected key
+ */
 const gchar*
-cryptui_key_list_get_selected_key (GtkTreeView *view)
+cryptui_key_list_get_selected_key (GtkTreeView *list)
 {
     GtkTreeModel *model;
     
-    model = gtk_tree_view_get_model (view);
+    model = gtk_tree_view_get_model (list);
     g_return_val_if_fail (CRYPTUI_IS_KEY_STORE (model), NULL);
     
-    return cryptui_key_store_get_selected_key (CRYPTUI_KEY_STORE (model), view);
+    return cryptui_key_store_get_selected_key (CRYPTUI_KEY_STORE (model), list);
 }
 
+/**
+ * cryptui_key_list_set_selected_key:
+ * @list: a CryptUIKeyList
+ * @key: the key to set
+ *
+ * Selects the given key in the list widget
+ *
+ * Returns: void
+ */
 void
-cryptui_key_list_set_selected_key (GtkTreeView *view, const gchar *key)
+cryptui_key_list_set_selected_key (GtkTreeView *list, const gchar *key)
 {
     GtkTreeModel *model;
     
-    model = gtk_tree_view_get_model (view);
+    model = gtk_tree_view_get_model (list);
     g_return_if_fail (CRYPTUI_IS_KEY_STORE (model));
     
-    cryptui_key_store_set_selected_key (CRYPTUI_KEY_STORE (model), view, key);
+    cryptui_key_store_set_selected_key (CRYPTUI_KEY_STORE (model), list, key);
 }
diff --git a/libcryptui/cryptui-key-list.h b/libcryptui/cryptui-key-list.h
index 17f9442..6a23456 100644
--- a/libcryptui/cryptui-key-list.h
+++ b/libcryptui/cryptui-key-list.h
@@ -45,20 +45,20 @@ void              cryptui_key_list_setup                (GtkTreeView *view,
                                                          CryptUIKeyStore *ckstore,
                                                          guint flags);
 
-CryptUIKeyStore*  cryptui_key_list_get_key_store        (GtkTreeView *combo);
+CryptUIKeyStore*  cryptui_key_list_get_key_store        (GtkTreeView *list);
 
-CryptUIKeyset*    cryptui_key_list_get_keyset           (GtkTreeView *combo);
+CryptUIKeyset*    cryptui_key_list_get_keyset           (GtkTreeView *list);
 
-gboolean          cryptui_key_list_have_selected_keys   (GtkTreeView *view);
+gboolean          cryptui_key_list_have_selected_keys   (GtkTreeView *list);
 
-GList*            cryptui_key_list_get_selected_keys    (GtkTreeView *view);
+GList*            cryptui_key_list_get_selected_keys    (GtkTreeView *list);
 
-void              cryptui_key_list_set_selected_keys    (GtkTreeView *view, 
+void              cryptui_key_list_set_selected_keys    (GtkTreeView *list, 
                                                          GList *keys);
 
-const gchar*      cryptui_key_list_get_selected_key     (GtkTreeView *view);
+const gchar*      cryptui_key_list_get_selected_key     (GtkTreeView *list);
 
-void              cryptui_key_list_set_selected_key     (GtkTreeView *view, 
+void              cryptui_key_list_set_selected_key     (GtkTreeView *list, 
                                                          const gchar *key);
 
 #endif /* __CRYPTUI_KEY_LIST_H__ */