[seahorse] Add gtk-doc annotations to cryptui-key-combo.c

[Adam Schreiber <sadam src gnome org>]

commit 5a367e6f1f462ed1758d6d354c0be03e6a37fe7a
Author: Adam Schreiber <sadam gnome org>
Date:   Sun May 3 21:01:32 2009 -0400

    Add gtk-doc annotations to cryptui-key-combo.c
---
 libcryptui/cryptui-key-combo.c |   88 +++++++++++++++++++++++++++++++---------
 1 files changed, 69 insertions(+), 19 deletions(-)

diff --git a/libcryptui/cryptui-key-combo.c b/libcryptui/cryptui-key-combo.c
index 37195f9..9903a78 100644
--- a/libcryptui/cryptui-key-combo.c
+++ b/libcryptui/cryptui-key-combo.c
@@ -1,24 +1,24 @@
-/* 
+/*
  * Seahorse
- * 
+ *
  * Copyright (C) 2005 Stefan Walter
- * 
- * This program is free software; you can redistribute it and/or modify 
+ *
+ * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU Lesser General Public License as
  * published by the Free Software Foundation; either version 2.1 of
  * the License, or (at your option) any later version.
- *  
+ *
  * This program is distributed in the hope that it will be useful, but
  * WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  * Lesser General Public License for more details.
- *  
+ *
  * You should have received a copy of the GNU Lesser General Public
  * License along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
- * 02111-1307, USA.  
+ * 02111-1307, USA.
  */
- 
+
 #include "config.h"
 #include <gtk/gtk.h>
 
@@ -27,8 +27,8 @@
 /* -----------------------------------------------------------------------------
  * INTERNAL
  */
- 
-static gboolean    
+
+static gboolean
 is_row_separator (GtkTreeModel *model, GtkTreeIter *iter, gpointer data)
 {
     gboolean ret;
@@ -40,7 +40,15 @@ is_row_separator (GtkTreeModel *model, GtkTreeIter *iter, gpointer data)
  * PUBLIC
  */
 
-GtkComboBox*  
+/**
+ * cryptui_key_combo_new:
+ * @ckstore: key store containing keys to be listed in the combo
+ *
+ * Creates a combobox containing the keys in ckstore
+ *
+ * Returns: the new CryptUIKeyCombo
+ */
+GtkComboBox*
 cryptui_key_combo_new (CryptUIKeyStore *ckstore)
 {
     GtkComboBox *combo = g_object_new (GTK_TYPE_COMBO_BOX, "model", ckstore, NULL);
@@ -48,22 +56,39 @@ cryptui_key_combo_new (CryptUIKeyStore *ckstore)
     return combo;
 }
 
+/**
+ * cryptui_key_combo_setup:
+ * @combo: a GtkComboBox
+ * @ckstore: key store containing keys to be listed in the combo
+ *
+ * Populates an existing GtkComboBox with keys from a CryptUIKeyStore
+ *
+ * Returns: void
+ */
 void
 cryptui_key_combo_setup (GtkComboBox *combo, CryptUIKeyStore *ckstore)
 {
     GtkCellRenderer *cell;
 
     gtk_combo_box_set_model (combo, GTK_TREE_MODEL (ckstore));
-    
+
     cell = gtk_cell_renderer_text_new ();
     gtk_cell_layout_pack_start (GTK_CELL_LAYOUT (combo), cell, TRUE);
     gtk_cell_layout_set_attributes (GTK_CELL_LAYOUT (combo), cell, "text", 0, NULL);
     g_object_set (G_OBJECT (cell), "ellipsize", PANGO_ELLIPSIZE_END, NULL);
-    
+
     gtk_combo_box_set_row_separator_func (combo, is_row_separator, NULL, NULL);
     cryptui_key_combo_set_key (combo, NULL);
 }
 
+/**
+ * cryptui_key_combo_get_key_store:
+ * @combo: a CryptUICombo
+ *
+ * Gets the key store from a CryptUiCombo
+ *
+ * Returns: the key store
+ */
 CryptUIKeyStore*
 cryptui_key_combo_get_key_store (GtkComboBox *combo)
 {
@@ -72,40 +97,65 @@ cryptui_key_combo_get_key_store (GtkComboBox *combo)
     return CRYPTUI_KEY_STORE (model);
 }
 
-CryptUIKeyset* 
+/**
+ * cryptui_key_combo_get_keyset:
+ * @combo: a CryptUICombo
+ *
+ * Gets the keyset stored in the combo's key store.
+ *
+ * Returns: a CryptuiKeyset
+ */
+CryptUIKeyset*
 cryptui_key_combo_get_keyset (GtkComboBox *combo)
 {
     CryptUIKeyStore *ckstore = cryptui_key_combo_get_key_store (combo);
     return ckstore ? cryptui_key_store_get_keyset (ckstore) : NULL;
 }
 
+/**
+ * cryptui_key_combo_set_key:
+ * @combo: a CryptUICombo
+ * @key: a CryptUI Key
+ *
+ * Sets the combo's current selection to the indicated key
+ *
+ * Returns: void
+ */
 void
 cryptui_key_combo_set_key (GtkComboBox *combo, const gchar *key)
 {
     GtkTreeModel *model = gtk_combo_box_get_model (combo);
     CryptUIKeyStore *ckstore;
     GtkTreeIter iter;
-    
+
     g_return_if_fail (CRYPTUI_IS_KEY_STORE (model));
     ckstore = CRYPTUI_KEY_STORE (model);
-    
+
     if (cryptui_key_store_get_iter_from_key (ckstore, key, &iter))
         gtk_combo_box_set_active_iter (combo, &iter);
 }
 
+/**
+ * cryptui_key_combo_get_key:
+ * @combo: a CryptUICombo
+ *
+ * Gets the currently selected key from the combo
+ *
+ * Returns: the currently selected key
+ */
 const gchar*
 cryptui_key_combo_get_key (GtkComboBox *combo)
 {
     GtkTreeModel *model = gtk_combo_box_get_model (combo);
     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))
         return cryptui_key_store_get_key_from_iter (ckstore, &iter);
-    
+
     return NULL;
 }