[gnome-keyring] gcr: Complete documentation for new components

From: Stefan Walter <stefw src gnome org>
To: commits-list gnome org
Cc:
Subject: [gnome-keyring] gcr: Complete documentation for new components
Date: Fri, 8 Apr 2011 18:47:31 +0000 (UTC)
commit d3c2b197e5ebe8a5968e00a260f1cb4acdc1454f
Author: Stef Walter <stefw collabora co uk>
Date:   Wed Apr 6 22:25:41 2011 +0200

    gcr: Complete documentation for new components

 docs/reference/gcr/gcr-docs.sgml    |   11 +++-
 docs/reference/gcr/gcr-sections.txt |  118 +++++++++++++++++++++++++++--
 gcr/gcr-certificate-renderer.c      |   24 ++++++-
 gcr/gcr-certificate-renderer.h      |    2 -
 gcr/gcr-certificate.c               |   34 ++++++++-
 gcr/gcr-certificate.h               |    2 +-
 gcr/gcr-collection-model.c          |  141 +++++++++++++++++++++++++++++++++--
 gcr/gcr-collection-model.h          |    9 +--
 gcr/gcr-collection.c                |   46 +++++++++++-
 gcr/gcr-collection.h                |    1 +
 gcr/gcr-column.c                    |   58 ++++++++++++++
 gcr/gcr-column.h                    |    6 +-
 gcr/gcr-comparable.c                |   43 +++++++++++
 gcr/gcr-importer.c                  |    2 +-
 gcr/gcr-importer.h                  |    2 +-
 gcr/gcr-key-renderer.c              |    1 -
 gcr/gcr-parser.c                    |    2 +-
 gcr/gcr-renderer.c                  |   14 +++-
 gcr/gcr-renderer.h                  |    6 --
 gcr/gcr-selector.c                  |   94 +++++++++++++++++++++++
 gcr/gcr-selector.h                  |   12 +--
 gcr/gcr-simple-collection.c         |   55 ++++++++++++++
 gcr/gcr-simple-collection.h         |    2 +
 gcr/gcr-viewer.c                    |    1 +
 24 files changed, 634 insertions(+), 52 deletions(-)
---
diff --git a/docs/reference/gcr/gcr-docs.sgml b/docs/reference/gcr/gcr-docs.sgml
index 86c4980..baaf986 100644
--- a/docs/reference/gcr/gcr-docs.sgml
+++ b/docs/reference/gcr/gcr-docs.sgml
@@ -21,10 +21,19 @@
 		<xi:include href="xml/gcr-certificate-chain.xml"/>
 	</part>
 
+	<part id="collections">
+		<title>Collections</title>
+		<xi:include href="xml/gcr-collection.xml"/>
+		<xi:include href="xml/gcr-comparable.xml"/>
+		<xi:include href="xml/gcr-simple-collection.xml"/>
+		<xi:include href="xml/gcr-collection-model.xml"/>
+	</part>
+
 	<part id="widgets">
-		<title>Widgets</title>
 		<xi:include href="xml/gcr-certificate-widget.xml"/>
 		<xi:include href="xml/gcr-key-widget.xml"/>
+		<xi:include href="xml/gcr-column.xml"/>
+		<xi:include href="xml/gcr-selector.xml"/>
 		<xi:include href="xml/gcr-renderer.xml"/>
 		<xi:include href="xml/gcr-viewer.xml"/>
 	</part>
diff --git a/docs/reference/gcr/gcr-sections.txt b/docs/reference/gcr/gcr-sections.txt
index 5034dcb..8951ccc 100644
--- a/docs/reference/gcr/gcr-sections.txt
+++ b/docs/reference/gcr/gcr-sections.txt
@@ -26,6 +26,8 @@ gcr_parser_get_type
 GCR_PARSER_CLASS
 GCR_IS_PARSER_CLASS
 GCR_PARSER_GET_CLASS
+GCK_API_SUBJECT_TO_CHANGE
+gcr_data_error_get_domain
 </SECTION>
 
 <SECTION>
@@ -53,7 +55,10 @@ gcr_certificate_mixin_class_init
 gcr_certificate_mixin_get_property
 GCR_CERTIFICATE_MIXIN_IMPLEMENT_COMPARABLE
 gcr_certificate_mixin_comparable_init
+gcr_certificate_compare
+gcr_certificate_get_icon
 <SUBSECTION Standard>
+gcr_certificate_get_columns
 GCR_CERTIFICATE
 GCR_IS_CERTIFICATE
 GCR_TYPE_CERTIFICATE
@@ -192,12 +197,114 @@ GcrCertificateChainPrivate
 </SECTION>
 
 <SECTION>
+<FILE>gcr-comparable</FILE>
+GcrComparable
+GcrComparableIface
+gcr_comparable_compare
+gcr_comparable_memcmp
+<SUBSECTION Standard>
+gcr_comparable_get_type
+GCR_COMPARABLE
+GCR_COMPARABLE_GET_INTERFACE
+GCR_IS_COMPARABLE
+GCR_TYPE_COMPARABLE
+</SECTION>
+
+<SECTION>
+<FILE>gcr-collection</FILE>
+GcrCollection
+gcr_collection_emit_added
+gcr_collection_emit_removed
+gcr_collection_get_length
+gcr_collection_get_objects
+<SUBSECTION Standard>
+gcr_collection_get_type
+GCR_COLLECTION
+GCR_COLLECTION_GET_INTERFACE
+GCR_IS_COLLECTION
+GCR_TYPE_COLLECTION
+GcrCollectionIface
+</SECTION>
+
+<SECTION>
+<FILE>gcr-simple-collection</FILE>
+GcrSimpleCollection
+GcrSimpleCollectionClass
+gcr_simple_collection_add
+gcr_simple_collection_contains
+gcr_simple_collection_new
+gcr_simple_collection_remove
+<SUBSECTION Standard>
+gcr_simple_collection_get_type
+GCR_IS_SIMPLE_COLLECTION
+GCR_IS_SIMPLE_COLLECTION_CLASS
+GCR_SIMPLE_COLLECTION
+GCR_SIMPLE_COLLECTION_CLASS
+GCR_SIMPLE_COLLECTION_GET_CLASS
+GCR_TYPE_SIMPLE_COLLECTION
+GcrSimpleCollectionPrivate
+</SECTION>
+
+<SECTION>
+<FILE>gcr-collection-model</FILE>
+GcrCollectionModel
+GcrCollectionModelClass
+gcr_collection_model_new
+gcr_collection_model_new_full
+gcr_collection_model_set_columns
+gcr_collection_model_iter_for_object
+gcr_collection_model_object_for_iter
+gcr_collection_model_get_selected
+gcr_collection_model_set_selected
+gcr_collection_model_toggle_selected
+gcr_collection_model_column_for_selected
+<SUBSECTION Standard>
+gcr_collection_model_get_type
+GCR_COLLECTION_MODEL
+GCR_COLLECTION_MODEL_CLASS
+GCR_COLLECTION_MODEL_GET_CLASS
+GCR_IS_COLLECTION_MODEL
+GCR_IS_COLLECTION_MODEL_CLASS
+GCR_TYPE_COLLECTION_MODEL
+GcrCollectionModelPrivate
+</SECTION>
+
+<SECTION>
+<FILE>gcr-column</FILE>
+GcrColumn
+GcrColumnFlags
+</SECTION>
+
+<SECTION>
+<FILE>gcr-selector</FILE>
+GcrSelector
+GcrSelectorClass
+GcrSelectorMode
+gcr_selector_get_collection
+gcr_selector_get_columns
+gcr_selector_get_mode
+gcr_selector_new
+<SUBSECTION Standard>
+gcr_selector_get_type
+gcr_selector_mode_get_type
+GCR_IS_SELECTOR
+GCR_IS_SELECTOR_CLASS
+GCR_SELECTOR
+GCR_SELECTOR_CLASS
+GCR_SELECTOR_GET_CLASS
+GCR_TYPE_SELECTOR
+GCR_TYPE_SELECTOR_MODE
+GcrSelectorPrivate
+</SECTION>
+
+<SECTION>
 <FILE>gcr-renderer</FILE>
 GcrRenderer
 GcrRendererIface
 gcr_renderer_create
 gcr_renderer_register
-gcr_renderer_render
+gcr_renderer_popuplate_popup
+gcr_renderer_render_view
 gcr_renderer_emit_data_changed
 <SUBSECTION Standard>
 gcr_renderer_get_type
@@ -227,6 +334,7 @@ GCR_VIEWER_GET_INTERFACE
 
 <SECTION>
 <FILE>gcr-certificate-widget</FILE>
+GCR_CERTIFICATE_COLUMNS
 GcrCertificateWidget
 GcrCertificateWidgetClass
 GcrCertificateRenderer
@@ -237,6 +345,7 @@ gcr_certificate_widget_set_attributes
 gcr_certificate_widget_get_certificate
 gcr_certificate_widget_set_certificate
 gcr_certificate_renderer_new
+gcr_certificate_renderer_new_for_attributes
 gcr_certificate_renderer_get_attributes
 gcr_certificate_renderer_set_attributes
 gcr_certificate_renderer_get_certificate
@@ -318,10 +427,3 @@ GCR_UNLOCK_OPTIONS_WIDGET_CLASS
 GCR_UNLOCK_OPTIONS_WIDGET_GET_CLASS
 GcrUnlockOptionsWidgetPrivate
 </SECTION>
-
-<SECTION>
-<FILE>gcr-misc</FILE>
-<SUBSECTION Standard>
-gcr_data_error_get_domain
-GCK_API_SUBJECT_TO_CHANGE
-</SECTION>
\ No newline at end of file
diff --git a/gcr/gcr-certificate-renderer.c b/gcr/gcr-certificate-renderer.c
index 77c5599..f0ffcef 100644
--- a/gcr/gcr-certificate-renderer.c
+++ b/gcr/gcr-certificate-renderer.c
@@ -40,7 +40,6 @@
 
 /**
  * GcrCertificateRenderer:
- * @parent: The parent object
  *
  * An implementation of #GcrRenderer which renders certificates.
  */
@@ -356,10 +355,21 @@ gcr_certificate_renderer_class_init (GcrCertificateRendererClass *klass)
 	           g_param_spec_object ("certificate", "Certificate", "Certificate to display.",
 	                                GCR_TYPE_CERTIFICATE, G_PARAM_READWRITE));
 
+	/**
+	 * GcrCertificateRenderer:attributes:
+	 *
+	 * The certificate attributes to display. One of the attributes must be
+	 * a CKA_VALUE type attribute which contains a DER encoded certificate.
+	 */
 	g_object_class_install_property (gobject_class, PROP_ATTRIBUTES,
 	           g_param_spec_boxed ("attributes", "Attributes", "Certificate pkcs11 attributes",
 	                               GCK_TYPE_ATTRIBUTES, G_PARAM_READWRITE));
 
+	/**
+	 * GcrCertificateRenderer:label:
+	 *
+	 * The label to display.
+	 */
 	g_object_class_install_property (gobject_class, PROP_LABEL,
 	           g_param_spec_string ("label", "Label", "Certificate Label",
 	                                "", G_PARAM_READWRITE));
@@ -617,6 +627,18 @@ gcr_certificate_renderer_new (GcrCertificate *certificate)
 	return g_object_new (GCR_TYPE_CERTIFICATE_RENDERER, "certificate", certificate, NULL);
 }
 
+/**
+ * gcr_certificate_renderer_new_for_attributes:
+ * @label: The label to display
+ * @attrs: The attributes to display
+ *
+ * Create a new certificate renderer to display the label and attributes. One
+ * of the attributes should be a CKA_VALUE type attribute containing a DER
+ * encoded certificate.
+ *
+ * Returns: A newly allocated #GcrCertificateRenderer, which should be released
+ *     with g_object_unref().
+ */
 GcrCertificateRenderer*
 gcr_certificate_renderer_new_for_attributes (const gchar *label, struct _GckAttributes *attrs)
 {
diff --git a/gcr/gcr-certificate-renderer.h b/gcr/gcr-certificate-renderer.h
index d93093d..c45f2ea 100644
--- a/gcr/gcr-certificate-renderer.h
+++ b/gcr/gcr-certificate-renderer.h
@@ -33,8 +33,6 @@
 
 G_BEGIN_DECLS
 
-#define GCR_TYPE_CERTIFICATE_COLUMNS                (gcr_certificate_renderer_get_columns ())
-
 #define GCR_TYPE_CERTIFICATE_RENDERER               (gcr_certificate_renderer_get_type ())
 #define GCR_CERTIFICATE_RENDERER(obj)               (G_TYPE_CHECK_INSTANCE_CAST ((obj), GCR_TYPE_CERTIFICATE_RENDERER, GcrCertificateRenderer))
 #define GCR_CERTIFICATE_RENDERER_CLASS(klass)       (G_TYPE_CHECK_CLASS_CAST ((klass), GCR_TYPE_CERTIFICATE_RENDERER, GcrCertificateRendererClass))
diff --git a/gcr/gcr-certificate.c b/gcr/gcr-certificate.c
index ab2f59a..c5d6403 100644
--- a/gcr/gcr-certificate.c
+++ b/gcr/gcr-certificate.c
@@ -72,6 +72,15 @@
  * The interface that implementors of #GcrCertificate must implement.
  */
 
+/**
+ * GCR_CERTIFICATE_COLUMNS:
+ *
+ * The columns that are valid for a certificate. This is to be used with
+ * the #GcrSelector or #GcrCollectionModel.
+ *
+ * This is an array of #GcrColumn, owned by the gcr library.
+ */
+
 /* 
  * The DER data in this structure is owned by the derived class. 
  * It is only valid for the duration of the current call stack
@@ -391,6 +400,20 @@ gcr_certificate_get_columns (void)
 	return columns;
 }
 
+/**
+ * gcr_certificate_compare:
+ * @first: The certificate to compare
+ * @other: The certificate to compare against
+ *
+ * Compare one certificate against another. If the certificates are equal
+ * then zero is returned. If one certificate is %NULL or not a certificate,
+ * then a non-zero value is returned.
+ *
+ * The return value is useful in a stable sort, but has no user logical
+ * meaning.
+ *
+ * Returns: zero if the certificates match, non-zero otherwise.
+ */
 gint
 gcr_certificate_compare (GcrComparable *first, GcrComparable *other)
 {
@@ -898,6 +921,15 @@ gcr_certificate_get_serial_number_hex (GcrCertificate *self)
 	return hex;
 }
 
+/**
+ * gcr_certificate_get_icon:
+ * @self: The certificate
+ *
+ * Get the icon for a certificate.
+ *
+ * Returns: The icon for this certificate, which should be released with
+ *     g_object_unref().
+ */
 GIcon*
 gcr_certificate_get_icon (GcrCertificate *self)
 {
@@ -943,7 +975,7 @@ gcr_certificate_mixin_comparable_init (GcrComparableIface *iface)
  * Initialize the certificate mixin for the class. This mixin implements the
  * various required properties for the certificate.
  *
- * Call this function near the end of your derived class_init() function. The
+ * Call this function near the end of your derived class_init function. The
  * derived class must implement the #GcrCertificate interface.
  */
 void
diff --git a/gcr/gcr-certificate.h b/gcr/gcr-certificate.h
index f180cf8..504b643 100644
--- a/gcr/gcr-certificate.h
+++ b/gcr/gcr-certificate.h
@@ -66,7 +66,7 @@ gconstpointer       gcr_certificate_get_der_data           (GcrCertificate *self
 
 const GcrColumn*    gcr_certificate_get_columns            (void);
 
-gint                gcr_certificate_compare                (GcrComparable *self,
+gint                gcr_certificate_compare                (GcrComparable *first,
                                                             GcrComparable *other);
 
 gchar*              gcr_certificate_get_issuer_cn          (GcrCertificate *self);
diff --git a/gcr/gcr-collection-model.c b/gcr/gcr-collection-model.c
index 9812d62..3dcb8a4 100644
--- a/gcr/gcr-collection-model.c
+++ b/gcr/gcr-collection-model.c
@@ -28,6 +28,45 @@
 #include <string.h>
 #include <unistd.h>
 
+/**
+ * SECTION:gcr-collection-model
+ * @title: GcrCollectionModel
+ * @short_description: A GtkTreeModel that represents a collection
+ *
+ * This is an implementation of #GtkTreeModel which represents the objects in
+ * the a #GcrCollection. As objects are added or removed from the collection,
+ * rows are added and removed from this model.
+ *
+ * The row values come from the properties of the objects in the collection. Use
+ * gcr_collection_model_new() to create a new collection model. To have more
+ * control over the values use a set of #GcrColumn structures to define the
+ * columns. This can be done with gcr_collection_model_new_full() or
+ * gcr_collection_model_set_columns().
+ *
+ * Each row can have a selected state, which is represented by a boolean column.
+ * The selected state can be toggled with gcr_collection_model_toggle_selected()
+ * or set with gcr_collection_model_set_selected() and retrieved with
+ * gcr_collection_model_get_selected().
+ *
+ * To determine which object a row represents and vice versa, use the
+ * gcr_collection_model_iter_for_object() or gcr_collection_model_object_for_iter()
+ * functions.
+ */
+
+/**
+ * GcrCollectionModel:
+ * @parent: The parent object
+ *
+ * A #GtkTreeModel which contains a row for each object in a #GcrCollection.
+ */
+
+/**
+ * GcrCollectionModelClass:
+ * @parent_class: The parent class
+ *
+ * The class for #GcrCollectionModel.
+ */
+
 #define COLLECTION_MODEL_STAMP 0xAABBCCDD
 
 enum {
@@ -569,6 +608,17 @@ gcr_collection_model_class_init (GcrCollectionModelClass *klass)
  * PUBLIC
  */
 
+/**
+ * gcr_collection_model_new:
+ * @collection: The collection to represent
+ * @...: The column names and types.
+ *
+ * Create a new #GcrCollectionModel. The variable argument list should contain
+ * pairs of property names, and #GType values. The variable argument list should
+ * be terminated with %NULL.
+ *
+ * Returns: A newly allocated model, which should be released with g_object_unref().
+ */
 GcrCollectionModel*
 gcr_collection_model_new (GcrCollection *collection, ...)
 {
@@ -598,6 +648,15 @@ gcr_collection_model_new (GcrCollection *collection, ...)
 	return self;
 }
 
+/**
+ * gcr_collection_model_new_full:
+ * @collection: The collection to represent
+ * @columns: The columns the model should contain
+ *
+ * Create a new #GcrCollectionModel.
+ *
+ * Returns: A newly allocated model, which should be released with g_object_unref().
+ */
 GcrCollectionModel*
 gcr_collection_model_new_full (GcrCollection *collection, const GcrColumn *columns)
 {
@@ -606,15 +665,27 @@ gcr_collection_model_new_full (GcrCollection *collection, const GcrColumn *colum
 	return self;
 }
 
-gint
+/**
+ * gcr_collection_model_set_columns:
+ * @self: The model
+ * @columns: The columns the model should contain
+ *
+ * Set the columns that the model should contain. @columns is an array of
+ * #GcrColumn structures, with the last one containing %NULL for all values.
+ *
+ * This function can only be called once, and only if the model was not created
+ * without a set of columns. This function cannot be called after the model
+ * has been added to a view.
+ */
+void
 gcr_collection_model_set_columns (GcrCollectionModel *self, const GcrColumn *columns)
 {
 	const GcrColumn *col;
 	guint n_columns;
 
-	g_return_val_if_fail (GCR_IS_COLLECTION_MODEL (self), -1);
-	g_return_val_if_fail (columns, -1);
-	g_return_val_if_fail (self->pv->n_columns == 0, -1);
+	g_return_if_fail (GCR_IS_COLLECTION_MODEL (self));
+	g_return_if_fail (columns);
+	g_return_if_fail (self->pv->n_columns == 0);
 
 	/* Count the number of columns, extra column for selected */
 	for (col = columns, n_columns = 1; col->property_name; ++col)
@@ -623,10 +694,17 @@ gcr_collection_model_set_columns (GcrCollectionModel *self, const GcrColumn *col
 	/* We expect the columns to stay around */
 	self->pv->columns = columns;
 	self->pv->n_columns = n_columns;
-
-	return n_columns + 1;
 }
 
+/**
+ * gcr_collection_model_object_for_iter:
+ * @self: The model
+ * @iter: The row
+ *
+ * Get the object that is represented by the given row in the model.
+ *
+ * Returns: The object, owned by the model.
+ */
 GObject*
 gcr_collection_model_object_for_iter (GcrCollectionModel *self, const GtkTreeIter *iter)
 {
@@ -638,6 +716,17 @@ gcr_collection_model_object_for_iter (GcrCollectionModel *self, const GtkTreeIte
 	return G_OBJECT (iter->user_data);
 }
 
+/**
+ * gcr_collection_model_iter_for_object:
+ * @self: The model
+ * @object: The object
+ * @iter: The row for the object
+ *
+ * Set @iter to the row for the given object. If the object is not in this
+ * model, then %FALSE will be returned.
+ *
+ * Returns: %TRUE if the object was present.
+ */
 gboolean
 gcr_collection_model_iter_for_object (GcrCollectionModel *self, GObject *object,
                                       GtkTreeIter *iter)
@@ -655,6 +744,15 @@ gcr_collection_model_iter_for_object (GcrCollectionModel *self, GObject *object,
 	return iter_for_index (self, index, iter);
 }
 
+/**
+ * gcr_collection_model_column_for_selected:
+ * @self: The model
+ *
+ * Get the column identifier for the column that contains the values
+ * of the selected state.
+ *
+ * Returns: The column identifier.
+ */
 gint
 gcr_collection_model_column_for_selected (GcrCollectionModel *self)
 {
@@ -663,6 +761,13 @@ gcr_collection_model_column_for_selected (GcrCollectionModel *self)
 	return self->pv->n_columns - 1;
 }
 
+/**
+ * gcr_collection_model_toggle_selected:
+ * @self: The model
+ * @iter: The row
+ *
+ * Toggle the selected state of a given row.
+ */
 void
 gcr_collection_model_toggle_selected (GcrCollectionModel *self, GtkTreeIter *iter)
 {
@@ -682,9 +787,18 @@ gcr_collection_model_toggle_selected (GcrCollectionModel *self, GtkTreeIter *ite
 		g_hash_table_insert (self->pv->selected, object, UNUSED_VALUE);
 }
 
+/**
+ * gcr_collection_model_set_selected:
+ * @self: The model
+ * @iter: The row
+ * @selected: Whether the row should be selected or not.
+ *
+ * Set whether a given row is toggled selected or not.
+ */
 void
 gcr_collection_model_set_selected (GcrCollectionModel *self, GtkTreeIter *iter, gboolean selected)
 {
+	GtkTreePath *path;
 	GObject *object;
 
 	g_return_if_fail (GCR_IS_COLLECTION_MODEL (self));
@@ -699,8 +813,23 @@ gcr_collection_model_set_selected (GcrCollectionModel *self, GtkTreeIter *iter,
 		g_hash_table_insert (self->pv->selected, object, UNUSED_VALUE);
 	else
 		g_hash_table_remove (self->pv->selected, object);
+
+	/* Tell the view that this row changed */
+	path = gtk_tree_model_get_path (GTK_TREE_MODEL (self), iter);
+	g_return_if_fail (path);
+	gtk_tree_model_row_changed (GTK_TREE_MODEL (self), path, iter);
+	gtk_tree_path_free (path);
 }
 
+/**
+ * gcr_collection_model_get_selected:
+ * @self: The model
+ * @iter: The row
+ *
+ * Check whether a given row has been toggled as selected.
+ *
+ * Returns: Whether the row has been selected.
+ */
 gboolean
 gcr_collection_model_get_selected (GcrCollectionModel *self, GtkTreeIter *iter)
 {
diff --git a/gcr/gcr-collection-model.h b/gcr/gcr-collection-model.h
index 931b1c3..d1e95f6 100644
--- a/gcr/gcr-collection-model.h
+++ b/gcr/gcr-collection-model.h
@@ -41,6 +41,7 @@ typedef struct _GcrCollectionModelPrivate GcrCollectionModelPrivate;
 struct _GcrCollectionModel {
 	GObject parent;
 
+	/*< private >*/
 	GcrCollectionModelPrivate *pv;
 };
 
@@ -56,7 +57,7 @@ GcrCollectionModel*   gcr_collection_model_new                 (GcrCollection *c
 GcrCollectionModel*   gcr_collection_model_new_full            (GcrCollection *collection,
                                                                 const GcrColumn *columns);
 
-gint                  gcr_collection_model_set_columns         (GcrCollectionModel *self,
+void                  gcr_collection_model_set_columns         (GcrCollectionModel *self,
                                                                 const GcrColumn *columns);
 
 GObject*              gcr_collection_model_object_for_iter     (GcrCollectionModel *self,
@@ -66,12 +67,6 @@ gboolean              gcr_collection_model_iter_for_object     (GcrCollectionMod
                                                                 GObject *object,
                                                                 GtkTreeIter *iter);
 
-gint                  gcr_collection_model_column_for_property (GcrCollectionModel *self,
-                                                                const gchar *property);
-
-gint                  gcr_collection_model_column_for_sortable (GcrCollectionModel *self,
-                                                                const gchar *property);
-
 gint                  gcr_collection_model_column_for_selected (GcrCollectionModel *self);
 
 void                  gcr_collection_model_toggle_selected     (GcrCollectionModel *self,
diff --git a/gcr/gcr-collection.c b/gcr/gcr-collection.c
index e7f962d..5493bbc 100644
--- a/gcr/gcr-collection.c
+++ b/gcr/gcr-collection.c
@@ -28,7 +28,18 @@
  * @title: GcrCollection
  * @short_description: A collection of objects.
  *
- * Xxxxx
+ * A #GcrCollection is used to group a set of objects. This is an abstract
+ * interface which can be used to determine which objects show up in a selector
+ * or other user interface element.
+ *
+ * Use gcr_simple_collection_new() to create a concrete implementation of this
+ * interface which you can add objects to.
+ */
+
+/**
+ * GcrCollection:
+ *
+ * A #GcrCollection is used to group a set of objects.
  */
 
 enum {
@@ -97,6 +108,14 @@ gcr_collection_get_type (void)
  */
 
 
+/**
+ * gcr_collection_get_length:
+ * @self: The collection
+ *
+ * Get the number of objects in this collection.
+ *
+ * Returns: The number of objects.
+ */
 guint
 gcr_collection_get_length (GcrCollection *self)
 {
@@ -105,6 +124,15 @@ gcr_collection_get_length (GcrCollection *self)
 	return GCR_COLLECTION_GET_INTERFACE (self)->get_length (self);
 }
 
+/**
+ * gcr_collection_get_objects:
+ * @self: The collection
+ *
+ * Get a list of the objects in this collection.
+ *
+ * Returns: A list of the objects in this collection, which should be freed
+ *     with g_list_free().
+ */
 GList*
 gcr_collection_get_objects (GcrCollection *self)
 {
@@ -113,6 +141,14 @@ gcr_collection_get_objects (GcrCollection *self)
 	return GCR_COLLECTION_GET_INTERFACE (self)->get_objects (self);
 }
 
+/**
+ * gcr_collection_emit_added:
+ * @self: The collection
+ * @object: The object that was added
+ *
+ * Emit the GcrCollection::added signal for the given object. This function
+ * is used by implementors of this interface.
+ */
 void
 gcr_collection_emit_added (GcrCollection *self, GObject *object)
 {
@@ -120,6 +156,14 @@ gcr_collection_emit_added (GcrCollection *self, GObject *object)
 	g_signal_emit (self, signals[ADDED], 0, object);
 }
 
+/**
+ * gcr_collection_emit_removed:
+ * @self: The collection
+ * @object: The object that was removed
+ *
+ * Emit the GcrCollection::removed signal for the given object. This function
+ * is used by implementors of this interface.
+ */
 void
 gcr_collection_emit_removed (GcrCollection *self, GObject *object)
 {
diff --git a/gcr/gcr-collection.h b/gcr/gcr-collection.h
index e00bcd4..4e572c6 100644
--- a/gcr/gcr-collection.h
+++ b/gcr/gcr-collection.h
@@ -49,6 +49,7 @@ struct _GcrCollectionIface {
 
 	GList* (*get_objects) (GcrCollection *self);
 
+	/*< private >*/
 	gpointer dummy1;
 	gpointer dummy2;
 	gpointer dummy3;
diff --git a/gcr/gcr-column.c b/gcr/gcr-column.c
new file mode 100644
index 0000000..826b0e3
--- /dev/null
+++ b/gcr/gcr-column.c
@@ -0,0 +1,58 @@
+/*
+ * gnome-keyring
+ *
+ * Copyright (C) 2011 Collabora Ltd.
+ *
+ * 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.
+ *
+ * Author: Stef Walter <stefw collabora co uk>
+ */
+
+#include "config.h"
+
+#include "gcr-column.h"
+
+/**
+ * SECTION:gcr-column
+ * @title: GcrColumn
+ * @short_description: Column information for selector or model.
+ *
+ * A #GcrColumn is used with #GcrSelector or #GcrCollectionModel to define
+ * the columns to display.
+ */
+
+/**
+ * GcrColumnFlags:
+ * @GCR_COLUMN_HIDDEN: Don't display this column.
+ * @GCR_COLUMN_SORTABLE: This column is sortable.
+ *
+ * Flags to be used with #GcrColumn
+ */
+
+/**
+ * GcrColumn:
+ * @property_name: The name of the property this column will display
+ * @property_type: The type of the property
+ * @column_type: The eventual type of the column
+ * @label: The display label for the column
+ * @flags: Flags from #GcrColumnFlags
+ * @transformer: A transformer function used to convert the value from
+ *     the property type to the column type. Can be %NULL if the types
+ *     are the same.
+ * @user_data: User data associated with the column
+ *
+ * Represents a column to display in a #GcrCollectionModel or #GcrSelector.
+ */
diff --git a/gcr/gcr-column.h b/gcr/gcr-column.h
index e6fe9ce..04de16d 100644
--- a/gcr/gcr-column.h
+++ b/gcr/gcr-column.h
@@ -28,10 +28,10 @@
 
 G_BEGIN_DECLS
 
-enum {
+typedef enum {
 	GCR_COLUMN_HIDDEN = 0x01,
 	GCR_COLUMN_SORTABLE = 0x02,
-};
+} GcrColumnFlags;
 
 typedef struct _GcrColumn {
 	const gchar *property_name;     /* The property to retrieve */
@@ -44,6 +44,8 @@ typedef struct _GcrColumn {
 	GValueTransform transformer;    /* The way to transform to this type or NULL */
 
 	gpointer user_data;
+
+	/*< private >*/
 	gpointer reserved;
 } GcrColumn;
 
diff --git a/gcr/gcr-comparable.c b/gcr/gcr-comparable.c
index 3f4d513..3d52c22 100644
--- a/gcr/gcr-comparable.c
+++ b/gcr/gcr-comparable.c
@@ -25,6 +25,27 @@
 
 #include <string.h>
 
+/**
+ * SECTION:gcr-comparable
+ * @title: GcrComparable
+ * @short_description: Interface for comparing objects
+ *
+ * The #GcrComparable interface is implemented by objects when they should be
+ * comparable against one another.
+ */
+
+/**
+ * GcrComparable:
+ *
+ * The #GcrComparable interface is implemented by comparable objects.
+ */
+
+/**
+ * GcrComparableIface:
+ *
+ * The interface to implement for #GcrComparable
+ */
+
 /* ---------------------------------------------------------------------------------
  * INTERFACE
  */
@@ -68,6 +89,16 @@ gcr_comparable_get_type (void)
  * PUBLIC
  */
 
+/**
+ * gcr_comparable_compare:
+ * @self: The comparable object
+ * @other: Another comparable object
+ *
+ * Compare whether two objects represent the same thing. The return value can
+ * also be used to sort the objects.
+ *
+ * Returns: Zero if the two objects represent the same thing, non-zero if not.
+ */
 gint
 gcr_comparable_compare (GcrComparable *self, GcrComparable *other)
 {
@@ -77,6 +108,18 @@ gcr_comparable_compare (GcrComparable *self, GcrComparable *other)
 	return GCR_COMPARABLE_GET_INTERFACE (self)->compare (self, other);
 }
 
+/**
+ * gcr_comparable_memcmp:
+ * @mem1: First block of memory
+ * @size1: Length of first block
+ * @mem2: Second lock of memory
+ * @size2: Length of second block
+ *
+ * Compare two blocks of memory. The return value can be used to sort
+ * the blocks of memory.
+ *
+ * Returns: Zero if the blocks are identical, non-zero if not.
+ */
 gint
 gcr_comparable_memcmp (gconstpointer mem1, gsize size1,
                        gconstpointer mem2, gsize size2)
diff --git a/gcr/gcr-importer.c b/gcr/gcr-importer.c
index 407833c..a885404 100644
--- a/gcr/gcr-importer.c
+++ b/gcr/gcr-importer.c
@@ -795,7 +795,7 @@ gcr_importer_set_prompt_behavior (GcrImporter *self, GcrImporterPromptBehavior b
 }
 
 /**
- * gcr_importer_import_async:
+ * gcr_importer_import:
  * @self: The importer
  * @cancellable: An optional cancellation object
  * @error: A location to raise an error on failure
diff --git a/gcr/gcr-importer.h b/gcr/gcr-importer.h
index 574052a..ae25bfa 100644
--- a/gcr/gcr-importer.h
+++ b/gcr/gcr-importer.h
@@ -87,7 +87,7 @@ void                      gcr_importer_listen                 (GcrImporter *self
                                                                GcrParser *parser);
 
 gboolean                  gcr_importer_import                 (GcrImporter *self,
-                                                               GCancellable *cancel,
+                                                               GCancellable *cancellable,
                                                                GError **error);
 
 void                      gcr_importer_import_async           (GcrImporter *self,
diff --git a/gcr/gcr-key-renderer.c b/gcr/gcr-key-renderer.c
index cbebcfd..0dcc87b 100644
--- a/gcr/gcr-key-renderer.c
+++ b/gcr/gcr-key-renderer.c
@@ -34,7 +34,6 @@
 
 /**
  * GcrKeyRenderer:
- * @parent: The parent object
  *
  * An implementation of #GcrRenderer which renders keys.
  */
diff --git a/gcr/gcr-parser.c b/gcr/gcr-parser.c
index ed31f08..2dc86cb 100644
--- a/gcr/gcr-parser.c
+++ b/gcr/gcr-parser.c
@@ -1726,7 +1726,7 @@ gcr_parser_parse_data (GcrParser *self, gconstpointer data,
 }
 
 /**
- * gcr_parser_format_disable:
+ * gcr_parser_format_enable:
  * @self: The parser
  * @format_id: The format identifier
  *
diff --git a/gcr/gcr-renderer.c b/gcr/gcr-renderer.c
index f60f782..7014239 100644
--- a/gcr/gcr-renderer.c
+++ b/gcr/gcr-renderer.c
@@ -51,9 +51,6 @@
 
 /**
  * GcrRendererIface:
- * @parent: The parent interface
- * @data_changed: The GcrRenderer::data-changed signal
- * @render: A virtual method to render the contents.
  *
  * The interface for #GcrRenderer
  */
@@ -128,7 +125,7 @@ gcr_renderer_get_type (void)
 }
 
 /**
- * gcr_renderer_render:
+ * gcr_renderer_render_view:
  * @self: The renderer
  * @viewer: The viewer to render to.
  *
@@ -142,6 +139,15 @@ gcr_renderer_render_view (GcrRenderer *self, GcrViewer *viewer)
 	GCR_RENDERER_GET_INTERFACE (self)->render_view (self, viewer);
 }
 
+/**
+ * gcr_renderer_popuplate_popup:
+ * @self: The renderer
+ * @viewer: The viewer that is displaying a popup
+ * @menu: The popup menu being displayed
+ *
+ * Called by #GcrViewer when about to display a popup menu for the content
+ * displayed by the renderer. The renderer can add a menu item if desired.
+ */
 void
 gcr_renderer_popuplate_popup (GcrRenderer *self, GcrViewer *viewer,
                               GtkMenu *menu)
diff --git a/gcr/gcr-renderer.h b/gcr/gcr-renderer.h
index 816c8f1..21164b8 100644
--- a/gcr/gcr-renderer.h
+++ b/gcr/gcr-renderer.h
@@ -71,12 +71,6 @@ void                      gcr_renderer_popuplate_popup            (GcrRenderer *
                                                                    GcrViewer *viewer,
                                                                    GtkMenu *menu);
 
-gchar*                    gcr_renderer_get_markup                 (GcrRenderer *self);
-
-gchar*                    gcr_renderer_get_description            (GcrRenderer *self);
-
-gchar*                    gcr_renderer_get_stock_icon             (GcrRenderer *self);
-
 void                      gcr_renderer_emit_data_changed          (GcrRenderer *self);
 
 GcrRenderer*              gcr_renderer_create                     (const gchar *label,
diff --git a/gcr/gcr-selector.c b/gcr/gcr-selector.c
index 08aba15..45be657 100644
--- a/gcr/gcr-selector.c
+++ b/gcr/gcr-selector.c
@@ -27,6 +27,38 @@
 
 #include <string.h>
 
+/**
+ * SECTION:gcr-selector
+ * @title: GcrSelector
+ * @short_description: A selector widget to select certificates or keys.
+ *
+ * The #GcrSelector can be used to select certificates or keys. The selector
+ * comes in one of two modes: %GCR_SELECTOR_MODE_SINGLE and
+ * %GCR_SELECTOR_MODE_MULTIPLE. The single selector mode allows the user to
+ * select one object at a time, and the multiple selector allows the user
+ * to select multiple objects from a list.
+ */
+
+/**
+ * GcrSelector:
+ *
+ * A selector widget.
+ */
+
+/**
+ * GcrSelectorClass:
+ *
+ * The class for #GcrSelector.
+ */
+
+/**
+ * GcrSelectorMode:
+ * @GCR_SELECTOR_MODE_SINGLE: User can select a single object.
+ * @GCR_SELECTOR_MODE_MULTIPLE: The user can select multiple objects.
+ *
+ * The mode for the selector.
+ */
+
 enum {
 	PROP_0,
 	PROP_COLLECTION,
@@ -34,6 +66,18 @@ enum {
 	PROP_MODE
 };
 
+struct _GcrSelector {
+	GtkAlignment parent;
+
+	/*< private >*/
+	GcrSelectorPrivate *pv;
+};
+
+struct _GcrSelectorClass {
+	/*< private >*/
+	GtkAlignmentClass parent_class;
+};
+
 struct _GcrSelectorPrivate {
 	GtkComboBox *combo;
 	GtkTreeView *tree;
@@ -410,14 +454,29 @@ gcr_selector_class_init (GcrSelectorClass *klass)
 
 	g_type_class_add_private (gobject_class, sizeof (GcrSelectorPrivate));
 
+	/**
+	 * GcrSelector:collection:
+	 *
+	 * The collection which contains the objects to display in the selector.
+	 */
 	g_object_class_install_property (gobject_class, PROP_COLLECTION,
 	           g_param_spec_object ("collection", "Collection", "Collection to select from",
 	                                GCR_TYPE_COLLECTION, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
 
+	/**
+	 * GcrSelector:columns:
+	 *
+	 * The columns to use to display the objects.
+	 */
 	g_object_class_install_property (gobject_class, PROP_COLUMNS,
 	           g_param_spec_pointer ("columns", "Columns", "Columns to display in multiple selector",
 	                                 G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
 
+	/**
+	 * GcrSelector:mode:
+	 *
+	 * The mode of the selector.
+	 */
 	g_object_class_install_property (gobject_class, PROP_MODE,
 	           g_param_spec_enum ("mode", "Mode", "The mode of the selector",
 	                              GCR_TYPE_SELECTOR_MODE, GCR_SELECTOR_MODE_SINGLE,
@@ -430,6 +489,17 @@ gcr_selector_class_init (GcrSelectorClass *klass)
  * PUBLIC
  */
 
+/**
+ * gcr_selector_new:
+ * @collection: The collection that contains the objects to display
+ * @columns: The columns to use to display the objects
+ * @mode: The mode of the selector
+ *
+ * Create a new #GcrSelector.
+ *
+ * Returns: A newly allocated selector, which should be released with
+ *     g_object_unref().
+ */
 GcrSelector*
 gcr_selector_new (GcrCollection *collection, const GcrColumn *columns, GcrSelectorMode mode)
 {
@@ -440,6 +510,14 @@ gcr_selector_new (GcrCollection *collection, const GcrColumn *columns, GcrSelect
 	                     NULL);
 }
 
+/**
+ * gcr_selector_get_collection:
+ * @self: The selector
+ *
+ * Get the collection that this selector is displaying objects from.
+ *
+ * Returns: The collection, owned by the selector.
+ */
 GcrCollection*
 gcr_selector_get_collection (GcrSelector *self)
 {
@@ -447,6 +525,14 @@ gcr_selector_get_collection (GcrSelector *self)
 	return self->pv->collection;
 }
 
+/**
+ * gcr_selector_get_columns:
+ * @self: The selector
+ *
+ * Get the columns displayed in a selector in multiple mode.
+ *
+ * Returns: The columns, owned by the selector.
+ */
 const GcrColumn*
 gcr_selector_get_columns (GcrSelector *self)
 {
@@ -454,6 +540,14 @@ gcr_selector_get_columns (GcrSelector *self)
 	return self->pv->columns;
 }
 
+/**
+ * gcr_selector_get_mode:
+ * @self: The selector
+ *
+ * Get the mode of the selector, whether single or multiple selection.
+ *
+ * Returns: The mode of the selector.
+ */
 GcrSelectorMode
 gcr_selector_get_mode (GcrSelector *self)
 {
diff --git a/gcr/gcr-selector.h b/gcr/gcr-selector.h
index 6ddf6a5..4ae13bd 100644
--- a/gcr/gcr-selector.h
+++ b/gcr/gcr-selector.h
@@ -45,14 +45,10 @@ typedef enum _GcrSelectorMode {
 	GCR_SELECTOR_MODE_MULTIPLE
 } GcrSelectorMode;
 
-struct _GcrSelector {
-	GtkAlignment parent;
-	GcrSelectorPrivate *pv;
-};
-
-struct _GcrSelectorClass {
-	GtkAlignmentClass parent_class;
-};
+/*
+ * TODO: GcrSelector and GcrSelectorClass are hidden until
+ * we can figure out what they should be derived from.
+ */
 
 GType                    gcr_selector_get_type               (void);
 
diff --git a/gcr/gcr-simple-collection.c b/gcr/gcr-simple-collection.c
index b88467a..4340532 100644
--- a/gcr/gcr-simple-collection.c
+++ b/gcr/gcr-simple-collection.c
@@ -27,6 +27,30 @@
 
 #include <string.h>
 
+/**
+ * SECTION:gcr-simple-collection
+ * @title: GcrSimpleCollection
+ * @short_description: A simple implementation of GcrCollection
+ *
+ * A simple implementation of #GcrCollection, which you can add and remove
+ * objects from. Use gcr_simple_collection_add() to do this
+ * gcr_simple_collection_remove().
+ */
+
+/**
+ * GcrSimpleCollection:
+ * @parent: The parent object
+ *
+ * A simple implementation of #GcrCollection.
+ */
+
+/**
+ * GcrSimpleCollectionClass:
+ * @parent_class: The parent class
+ *
+ * The class for #GcrSimpleCollection.
+ */
+
 struct _GcrSimpleCollectionPrivate {
 	GHashTable *items;
 };
@@ -106,12 +130,27 @@ gcr_collection_iface (GcrCollectionIface *iface)
  * PUBLIC
  */
 
+/**
+ * gcr_simple_collection_new:
+ *
+ * Create a new #GcrSimpleCollection.
+ *
+ * Returns: A newly allocated collection, which should be freed with
+ *     g_object_unref().
+ */
 GcrCollection*
 gcr_simple_collection_new (void)
 {
 	return g_object_new (GCR_TYPE_SIMPLE_COLLECTION, NULL);
 }
 
+/**
+ * gcr_simple_collection_add:
+ * @self: The collection
+ * @object: The object to add
+ *
+ * Add an object to this collection
+ */
 void
 gcr_simple_collection_add (GcrSimpleCollection *self, GObject *object)
 {
@@ -122,6 +161,13 @@ gcr_simple_collection_add (GcrSimpleCollection *self, GObject *object)
 	gcr_collection_emit_added (GCR_COLLECTION (self), object);
 }
 
+/**
+ * gcr_simple_collection_remove:
+ * @self: The collection
+ * @object: The object to remove from the collection
+ *
+ * Remove an object from the collection.
+ */
 void
 gcr_simple_collection_remove (GcrSimpleCollection *self, GObject *object)
 {
@@ -134,6 +180,15 @@ gcr_simple_collection_remove (GcrSimpleCollection *self, GObject *object)
 	g_object_unref (object);
 }
 
+/**
+ * gcr_simple_collection_contains:
+ * @self: The collection
+ * @object: The object to check
+ *
+ * Check if the collection contains a certain object.
+ *
+ * Returns: %TRUE if the collection contains the object.
+ */
 gboolean
 gcr_simple_collection_contains (GcrSimpleCollection *self, GObject *object)
 {
diff --git a/gcr/gcr-simple-collection.h b/gcr/gcr-simple-collection.h
index beccb0b..3ee0947 100644
--- a/gcr/gcr-simple-collection.h
+++ b/gcr/gcr-simple-collection.h
@@ -42,6 +42,8 @@ typedef struct _GcrSimpleCollectionPrivate GcrSimpleCollectionPrivate;
 
 struct _GcrSimpleCollection {
 	GObject parent;
+
+	/*< private >*/
 	GcrSimpleCollectionPrivate *pv;
 };
 
diff --git a/gcr/gcr-viewer.c b/gcr/gcr-viewer.c
index 36f0bae..e3b5c68 100644
--- a/gcr/gcr-viewer.c
+++ b/gcr/gcr-viewer.c
@@ -55,6 +55,7 @@
  *
  * The interface for #GcrViewer
  */
+
 static void
 gcr_viewer_base_init (gpointer gobject_iface)
 {
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]