GNOME.org
 

[gnome-keyring] gcr: More introspection and documentation cleanup

commit 8edab1121205ae42c9005219f474af38881d8572
Author: Stef Walter <stefw collabora co uk>
Date:   Thu Sep 29 15:03:39 2011 +0200

    gcr: More introspection and documentation cleanup
    
     * Tag proper transfer on return values
     * Use guchar * for arrays of bytes

 docs/reference/gcr/gcr-docs.sgml     |    4 +++
 gcr/gcr-certificate-basics-widget.c  |    4 +-
 gcr/gcr-certificate-chain.c          |    6 ++--
 gcr/gcr-certificate-details-widget.c |    4 +-
 gcr/gcr-certificate-renderer.c       |   23 ++++++++--------
 gcr/gcr-certificate-widget.c         |   12 ++++----
 gcr/gcr-certificate.c                |    6 +++-
 gcr/gcr-certificate.h                |    3 +-
 gcr/gcr-collection-model.c           |   10 ++++---
 gcr/gcr-collection.c                 |   14 ++++++++++
 gcr/gcr-comparable.c                 |    2 +-
 gcr/gcr-import-button.c              |    4 +-
 gcr/gcr-key-renderer.c               |    4 +-
 gcr/gcr-library.c                    |   28 ++++++++++++++++++++
 gcr/gcr-list-selector.c              |    6 ++--
 gcr/gcr-parser.c                     |   47 ++++++++++++++++++++++++++++-----
 gcr/gcr-parser.h                     |    2 +-
 gcr/gcr-pkcs11-certificate.c         |    5 ++-
 gcr/gcr-renderer.c                   |   11 ++++++++
 gcr/gcr-simple-certificate.c         |   17 +++++++-----
 gcr/gcr-simple-certificate.h         |    4 +-
 gcr/gcr-tree-selector.c              |    8 +++---
 gcr/gcr-types.h                      |    4 +-
 gcr/gcr-viewer-widget.c              |   21 ++++++++++++++-
 gcr/gcr-viewer-widget.h              |    2 +-
 gcr/gcr-viewer-window.c              |   16 +++++++++++-
 gcr/gcr-viewer.c                     |    8 ++++++
 gcr/tests/frob-parser.c              |    2 +-
 gcr/tests/test-certificate-chain.c   |    2 +-
 gcr/tests/test-certificate.c         |    6 ++--
 gcr/tests/test-parser.c              |    4 +-
 gcr/tests/test-trust.c               |    2 +-
 32 files changed, 216 insertions(+), 75 deletions(-)
---
diff --git a/docs/reference/gcr/gcr-docs.sgml b/docs/reference/gcr/gcr-docs.sgml
index 8d0de72..f995d32 100644
--- a/docs/reference/gcr/gcr-docs.sgml
+++ b/docs/reference/gcr/gcr-docs.sgml
@@ -59,4 +59,8 @@
 		<xi:include href="xml/gcr-library.xml"/>
 		<xi:include href="xml/gcr-misc.xml"/>
 	</part>
+
+	<xi:include href="xml/annotation-glossary.xml">
+		<xi:fallback />
+	</xi:include>
 </book>
diff --git a/gcr/gcr-certificate-basics-widget.c b/gcr/gcr-certificate-basics-widget.c
index 1638b33..5e4e5c7 100644
--- a/gcr/gcr-certificate-basics-widget.c
+++ b/gcr/gcr-certificate-basics-widget.c
@@ -35,7 +35,7 @@ gcr_certificate_basics_widget_get_type (void)
 /**
  * gcr_certificate_basics_widget_new: (skip):
  *
- * Deprecated
+ * Deprecated: Since 2.30
  */
 GcrCertificateBasicsWidget *
 gcr_certificate_basics_widget_new (GcrCertificate *cert)
@@ -46,7 +46,7 @@ gcr_certificate_basics_widget_new (GcrCertificate *cert)
 /**
  * gcr_certificate_basics_widget_get_certificate: (skip):
  *
- * Deprecated
+ * Deprecated: Since 2.30
  */
 GcrCertificate *
 gcr_certificate_basics_widget_get_certificate (GcrCertificateBasicsWidget *basics)
diff --git a/gcr/gcr-certificate-chain.c b/gcr/gcr-certificate-chain.c
index 5e425c9..7ccf495 100644
--- a/gcr/gcr-certificate-chain.c
+++ b/gcr/gcr-certificate-chain.c
@@ -517,9 +517,9 @@ gcr_certificate_chain_class_init (GcrCertificateChainClass *klass)
  *
  * Create a new #GcrCertificateChain.
  *
- * Returns: A newly allocated #GcrCertificateChain
+ * Returns: (transfer full): a newly allocated certificate chain
  */
-GcrCertificateChain*
+GcrCertificateChain *
 gcr_certificate_chain_new (void)
 {
 	return g_object_new (GCR_TYPE_CERTIFICATE_CHAIN, NULL);
@@ -583,7 +583,7 @@ gcr_certificate_chain_get_status (GcrCertificateChain *self)
  * If an anchor is returned it does not mean that the certificate chain has
  * been verified, but merely that an anchor has been found.
  *
- * Returns: (transfer full): the anchor certificate, or NULL if not anchored.
+ * Returns: (transfer none): the anchor certificate, or NULL if not anchored.
  */
 GcrCertificate *
 gcr_certificate_chain_get_anchor (GcrCertificateChain *self)
diff --git a/gcr/gcr-certificate-details-widget.c b/gcr/gcr-certificate-details-widget.c
index 870acbb..7cf9db3 100644
--- a/gcr/gcr-certificate-details-widget.c
+++ b/gcr/gcr-certificate-details-widget.c
@@ -35,7 +35,7 @@ gcr_certificate_details_widget_get_type (void)
 /**
  * gcr_certificate_details_widget_new: (skip):
  *
- * Deprecated
+ * Deprecated: Since 2.30
  */
 GcrCertificateDetailsWidget*
 gcr_certificate_details_widget_new (GcrCertificate *cert)
@@ -46,7 +46,7 @@ gcr_certificate_details_widget_new (GcrCertificate *cert)
 /**
  * gcr_certificate_details_widget_get_certificate: (skip):
  *
- * Deprecated
+ * Deprecated: Since 2.30
  */
 GcrCertificate*
 gcr_certificate_details_widget_get_certificate (GcrCertificateDetailsWidget *details)
diff --git a/gcr/gcr-certificate-renderer.c b/gcr/gcr-certificate-renderer.c
index f374536..aaa9b9d 100644
--- a/gcr/gcr-certificate-renderer.c
+++ b/gcr/gcr-certificate-renderer.c
@@ -752,8 +752,9 @@ gcr_renderer_iface_init (GcrRendererIface *iface)
 	iface->render_view = gcr_certificate_renderer_render;
 }
 
-static gconstpointer
-gcr_certificate_renderer_get_der_data (GcrCertificate *cert, gsize *n_data)
+static const guchar *
+gcr_certificate_renderer_get_der_data (GcrCertificate *cert,
+                                       gsize *n_data)
 {
 	GcrCertificateRenderer *self = GCR_CERTIFICATE_RENDERER (cert);
 	GckAttribute *attr;
@@ -789,10 +790,10 @@ gcr_renderer_certificate_iface_init (GcrCertificateIface *iface)
  *
  * Create a new certificate renderer to display the certificate.
  *
- * Returns: A newly allocated #GcrCertificateRenderer, which should be released
- *     with g_object_unref().
+ * Returns: (transfer full): a newly allocated #GcrCertificateRenderer, which
+ *          should be released with g_object_unref()
  */
-GcrCertificateRenderer*
+GcrCertificateRenderer *
 gcr_certificate_renderer_new (GcrCertificate *certificate)
 {
 	return g_object_new (GCR_TYPE_CERTIFICATE_RENDERER, "certificate", certificate, NULL);
@@ -807,10 +808,10 @@ gcr_certificate_renderer_new (GcrCertificate *certificate)
  * 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().
+ * Returns: (transfer full): a newly allocated #GcrCertificateRenderer, which
+ *          should be released with g_object_unref()
  */
-GcrCertificateRenderer*
+GcrCertificateRenderer *
 gcr_certificate_renderer_new_for_attributes (const gchar *label, struct _GckAttributes *attrs)
 {
 	return g_object_new (GCR_TYPE_CERTIFICATE_RENDERER, "label", label, "attributes", attrs, NULL);
@@ -824,7 +825,7 @@ gcr_certificate_renderer_new_for_attributes (const gchar *label, struct _GckAttr
  * explicitly set, then the renderer will return itself since it acts as
  * a valid certificate.
  *
- * Returns: (transfer full): The certificate, owned by the renderer.
+ * Returns: (transfer none): The certificate, owned by the renderer.
  */
 GcrCertificate *
 gcr_certificate_renderer_get_certificate (GcrCertificateRenderer *self)
@@ -868,9 +869,9 @@ gcr_certificate_renderer_set_certificate (GcrCertificateRenderer *self, GcrCerti
  *
  * Get the PKCS\#11 attributes, if any, set for this renderer to display.
  *
- * Returns: The attributes, owned by the renderer.
+ * Returns: (transfer none): the attributes, owned by the renderer
  */
-GckAttributes*
+GckAttributes *
 gcr_certificate_renderer_get_attributes (GcrCertificateRenderer *self)
 {
 	g_return_val_if_fail (GCR_IS_CERTIFICATE_RENDERER (self), NULL);
diff --git a/gcr/gcr-certificate-widget.c b/gcr/gcr-certificate-widget.c
index 24dc6ee..ad93b14 100644
--- a/gcr/gcr-certificate-widget.c
+++ b/gcr/gcr-certificate-widget.c
@@ -196,10 +196,10 @@ gcr_certificate_widget_class_init (GcrCertificateWidgetClass *klass)
  *
  * Create a new certificate widget which displays a given certificate.
  *
- * Returns: A newly allocated #GcrCertificateWidget, which should be freed
- *     with g_object_unref().
+ * Returns: (transfer full): a newly allocated #GcrCertificateWidget, which
+ *          should be freed with g_object_unref()
  */
-GcrCertificateWidget*
+GcrCertificateWidget *
 gcr_certificate_widget_new (GcrCertificate *certificate)
 {
 	return g_object_new (GCR_TYPE_CERTIFICATE_WIDGET, "certificate", certificate, NULL);
@@ -211,7 +211,7 @@ gcr_certificate_widget_new (GcrCertificate *certificate)
  *
  * Get the certificate displayed in the widget.
  *
- * Returns: (transfer full): The certificate.
+ * Returns: (transfer none): the certificate
  */
 GcrCertificate *
 gcr_certificate_widget_get_certificate (GcrCertificateWidget *self)
@@ -241,9 +241,9 @@ gcr_certificate_widget_set_certificate (GcrCertificateWidget *self, GcrCertifica
  * Get the attributes displayed in the widget. The attributes should contain
  * a certificate.
  *
- * Returns: The attributes, owned by the widget.
+ * Returns: (transfer none): the attributes, owned by the widget
  */
-GckAttributes*
+GckAttributes *
 gcr_certificate_widget_get_attributes (GcrCertificateWidget *self)
 {
 	g_return_val_if_fail (GCR_IS_CERTIFICATE_WIDGET (self), NULL);
diff --git a/gcr/gcr-certificate.c b/gcr/gcr-certificate.c
index ea0609d..1e716df 100644
--- a/gcr/gcr-certificate.c
+++ b/gcr/gcr-certificate.c
@@ -69,6 +69,8 @@
 
 /**
  * GcrCertificateIface:
+ * @parent: the parent interface type
+ * @get_der_data: a method which returns the RAW der data of the certificate
  *
  * The interface that implementors of #GcrCertificate must implement.
  */
@@ -362,11 +364,11 @@ G_DEFINE_INTERFACE (GcrCertificate, gcr_certificate, GCR_TYPE_COMPARABLE);
  */
 
 /**
- * gcr_certificate_get_columns: (skip):
+ * gcr_certificate_get_columns: (skip)
  *
  * Get the columns appropriate for a certificate
  *
- * Returns: the columns
+ * Returns: (transfer none): the columns
  */
 const GcrColumn*
 gcr_certificate_get_columns (void)
diff --git a/gcr/gcr-certificate.h b/gcr/gcr-certificate.h
index b574a23..d60be22 100644
--- a/gcr/gcr-certificate.h
+++ b/gcr/gcr-certificate.h
@@ -47,7 +47,8 @@ typedef struct _GcrCertificateIface     GcrCertificateIface;
 struct _GcrCertificateIface {
 	GTypeInterface parent;
 
-	gconstpointer (*get_der_data) (GcrCertificate *self, gsize *n_data);
+	const guchar * (*get_der_data) (GcrCertificate *self,
+	                                gsize *n_data);
 
 	/*< private >*/
 	gpointer dummy1;
diff --git a/gcr/gcr-collection-model.c b/gcr/gcr-collection-model.c
index b229929..a423e26 100644
--- a/gcr/gcr-collection-model.c
+++ b/gcr/gcr-collection-model.c
@@ -1249,7 +1249,8 @@ gcr_collection_model_class_init (GcrCollectionModelClass *klass)
  * 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().
+ * Returns: (transfer full): a newly allocated model, which should be released
+ *          with g_object_unref().
  */
 GcrCollectionModel*
 gcr_collection_model_new (GcrCollection *collection, ...)
@@ -1280,13 +1281,14 @@ gcr_collection_model_new (GcrCollection *collection, ...)
 }
 
 /**
- * gcr_collection_model_new_full: (skip):
+ * gcr_collection_model_new_full: (skip)
  * @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().
+ * Returns: (transfer full): a newly allocated model, which should be released
+ *          with g_object_unref()
  */
 GcrCollectionModel*
 gcr_collection_model_new_full (GcrCollection *collection, const GcrColumn *columns)
@@ -1297,7 +1299,7 @@ gcr_collection_model_new_full (GcrCollection *collection, const GcrColumn *colum
 }
 
 /**
- * gcr_collection_model_set_columns: (skip):
+ * gcr_collection_model_set_columns: (skip)
  * @self: The model
  * @columns: The columns the model should contain
  *
diff --git a/gcr/gcr-collection.c b/gcr/gcr-collection.c
index 3b7bca4..08bbedb 100644
--- a/gcr/gcr-collection.c
+++ b/gcr/gcr-collection.c
@@ -62,11 +62,25 @@ gcr_collection_default_init (GcrCollectionIface *iface)
 
 	if (g_once_init_enter (&initialized)) {
 
+		/**
+		 * GcrCollection::added:
+		 * @self: the collection
+		 * @object: (type GLib.Object): object that was added
+		 *
+		 * This signal is emitted when an object is added to the collection.
+		 */
 		signals[ADDED] = g_signal_new ("added", GCR_TYPE_COLLECTION,
 		                               G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GcrCollectionIface, added),
 		                               NULL, NULL, g_cclosure_marshal_VOID__OBJECT,
 		                               G_TYPE_NONE, 1, G_TYPE_OBJECT);
 
+		/**
+		 * GcrCollection::removed:
+		 * @self: the collection
+		 * @object: (type GLib.Object): object that was removed
+		 *
+		 * This signal is emitted when an object is removed from the collection.
+		 */
 		signals[REMOVED] = g_signal_new ("removed", GCR_TYPE_COLLECTION,
 		                                 G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GcrCollectionIface, removed),
 		                                 NULL, NULL, g_cclosure_marshal_VOID__OBJECT,
diff --git a/gcr/gcr-comparable.c b/gcr/gcr-comparable.c
index 3d52c22..fddbdd1 100644
--- a/gcr/gcr-comparable.c
+++ b/gcr/gcr-comparable.c
@@ -109,7 +109,7 @@ gcr_comparable_compare (GcrComparable *self, GcrComparable *other)
 }
 
 /**
- * gcr_comparable_memcmp:
+ * gcr_comparable_memcmp: (skip)
  * @mem1: First block of memory
  * @size1: Length of first block
  * @mem2: Second lock of memory
diff --git a/gcr/gcr-import-button.c b/gcr/gcr-import-button.c
index 3dd09cf..9614634 100644
--- a/gcr/gcr-import-button.c
+++ b/gcr/gcr-import-button.c
@@ -493,9 +493,9 @@ gcr_import_button_class_init (GcrImportButtonClass *klass)
  *
  * Create a new #GcrImportButton.
  *
- * Returns: a newly created #GcrImportButton
+ * Returns: (transfer full): a newly created #GcrImportButton
  */
-GcrImportButton*
+GcrImportButton *
 gcr_import_button_new (const gchar *label)
 {
 	return g_object_new (GCR_TYPE_IMPORT_BUTTON,
diff --git a/gcr/gcr-key-renderer.c b/gcr/gcr-key-renderer.c
index cbbdab4..aed920b 100644
--- a/gcr/gcr-key-renderer.c
+++ b/gcr/gcr-key-renderer.c
@@ -356,8 +356,8 @@ gcr_key_renderer_renderer_iface (GcrRendererIface *iface)
  *
  * Create a new key renderer which renders a given key in the attributes.
  *
- * Returns: A newly allocated #GcrKeyRenderer, which should be freed
- *     with g_object_unref().
+ * Returns: (transfer full): a newly allocated #GcrKeyRenderer, which should be
+ *          freed with g_object_unref()
  */
 GcrKeyRenderer*
 gcr_key_renderer_new (const gchar *label, GckAttributes *attrs)
diff --git a/gcr/gcr-library.c b/gcr/gcr-library.c
index f94aa0a..1bde8dd 100644
--- a/gcr/gcr-library.c
+++ b/gcr/gcr-library.c
@@ -210,6 +210,14 @@ on_initialize_registered (GObject *object,
 	g_object_unref (res);
 }
 
+/**
+ * gcr_pkcs11_initialize_async:
+ * @cancellable: optional cancellable used to cancel the operation
+ * @callback: callback which will be called when the operation completes
+ * @user_data: data passed to the callback
+ *
+ * Asynchronously initialize the registered PKCS\#11 modules.
+ */
 void
 gcr_pkcs11_initialize_async (GCancellable *cancellable,
                              GAsyncReadyCallback callback,
@@ -233,6 +241,16 @@ gcr_pkcs11_initialize_async (GCancellable *cancellable,
 	g_object_unref (res);
 }
 
+/**
+ * gcr_pkcs11_initialize_finish:
+ * @result: the asynchronous result
+ * @error: location to place an error on failure
+ *
+ * Complete the asynchronous operation to initialize the registered PKCS\#11
+ * modules.
+ *
+ * Returns: whether the operation was successful or not.
+ */
 gboolean
 gcr_pkcs11_initialize_finish (GAsyncResult *result,
                               GError **error)
@@ -246,6 +264,16 @@ gcr_pkcs11_initialize_finish (GAsyncResult *result,
 	return TRUE;
 }
 
+/**
+ * gcr_pkcs11_initialize:
+ * @cancellable: optional cancellable used to cancel the operation
+ * @error: location to place an error on failure
+ *
+ * Asynchronously initialize the registered PKCS\#11 modules.
+ *
+ * Returns: whether the operation was successful or not.
+ */
+
 gboolean
 gcr_pkcs11_initialize (GCancellable *cancellable,
                        GError **error)
diff --git a/gcr/gcr-list-selector.c b/gcr/gcr-list-selector.c
index b878541..87d354e 100644
--- a/gcr/gcr-list-selector.c
+++ b/gcr/gcr-list-selector.c
@@ -363,10 +363,10 @@ gcr_list_selector_class_init (GcrListSelectorClass *klass)
  *
  * Create a new #GcrListSelector.
  *
- * Returns: A newly allocated selector, which should be released with
- *     g_object_unref().
+ * Returns: (transfer full): a newly allocated selector, which should be
+ *          released with g_object_unref()
  */
-GcrListSelector*
+GcrListSelector *
 gcr_list_selector_new (GcrCollection *collection)
 {
 	return g_object_new (GCR_TYPE_LIST_SELECTOR,
diff --git a/gcr/gcr-parser.c b/gcr/gcr-parser.c
index 483c8ab..ca1e809 100644
--- a/gcr/gcr-parser.c
+++ b/gcr/gcr-parser.c
@@ -2083,9 +2083,9 @@ gcr_parser_class_init (GcrParserClass *klass)
  *
  * Create a new #GcrParser
  *
- * Returns: A newly allocated #GcrParser
+ * Returns: (transfer full): a newly allocated #GcrParser
  */
-GcrParser*
+GcrParser *
 gcr_parser_new (void)
 {
 	return g_object_new (GCR_TYPE_PARSER, NULL);
@@ -2109,7 +2109,7 @@ gcr_parser_add_password (GcrParser *self, const gchar *password)
 /**
  * gcr_parser_parse_data:
  * @self: The parser
- * @data: The data to parse
+ * @data: (array length=n_data): the data to parse
  * @n_data: The length of the data
  * @error: A location to raise an error on failure.
  *
@@ -2119,8 +2119,10 @@ gcr_parser_add_password (GcrParser *self, const gchar *password)
  * Returns: Whether the data was parsed successfully or not.
  */
 gboolean
-gcr_parser_parse_data (GcrParser *self, gconstpointer data,
-                       gsize n_data, GError **error)
+gcr_parser_parse_data (GcrParser *self,
+                       const guchar *data,
+                       gsize n_data,
+                       GError **error)
 {
 	ForeachArgs args = { self, data, n_data, GCR_ERROR_UNRECOGNIZED };
 	const gchar *message = NULL;
@@ -2251,6 +2253,14 @@ gcr_parser_format_supported (GcrParser *self,
 	return parser_format_lookup (format) ? TRUE : FALSE;
 }
 
+/**
+ * gcr_parser_get_parsed:
+ * @self: a parser
+ *
+ * Get the currently parsed item
+ *
+ * Returns: (transfer none): the currently parsed item
+ */
 GcrParsed *
 gcr_parser_get_parsed (GcrParser *self)
 {
@@ -2272,6 +2282,15 @@ gcr_parsed_get_type (void)
 	return type;
 }
 
+/**
+ * gcr_parsed_ref:
+ * @parsed: a parsed item
+ *
+ * Add a reference to a parsed item. An item may not be shared across threads
+ * until it has been referenced at least once.
+ *
+ * Returns: (transfer full): the parsed item
+ */
 GcrParsed *
 gcr_parsed_ref (GcrParsed *parsed)
 {
@@ -2317,6 +2336,12 @@ gcr_parsed_ref (GcrParsed *parsed)
 	return copy;
 }
 
+/**
+ * gcr_parsed_unref:
+ * @parsed: a parsed item
+ *
+ * Unreferences a parsed item which was referenced with gcr_parsed_ref()
+ */
 void
 gcr_parsed_unref (gpointer parsed)
 {
@@ -2353,6 +2378,14 @@ gcr_parser_get_parsed_description (GcrParser *self)
 	return gcr_parsed_get_description (self->pv->parsed);
 }
 
+/**
+ * gcr_parsed_get_description:
+ * @parsed: a parsed item
+ *
+ * Get the descirption for a parsed item.
+ *
+ * Returns: the description
+ */
 const gchar*
 gcr_parsed_get_description (GcrParsed *parsed)
 {
@@ -2390,8 +2423,8 @@ gcr_parser_get_parsed_attributes (GcrParser *self)
  *
  * Get the attributes which make up the parsed item.
  *
- * Returns: The attributes for the item. These are owned by the parsed
- *          item and should not be freed.
+ * Returns: (transfer none): the attributes for the item; these are owned by
+ *          the parsed item and should not be freed
  */
 GckAttributes *
 gcr_parsed_get_attributes (GcrParsed *parsed)
diff --git a/gcr/gcr-parser.h b/gcr/gcr-parser.h
index 09c0687..99a7e87 100644
--- a/gcr/gcr-parser.h
+++ b/gcr/gcr-parser.h
@@ -77,7 +77,7 @@ gboolean                 gcr_parser_format_supported       (GcrParser *self,
                                                             GcrDataFormat format);
 
 gboolean                 gcr_parser_parse_data             (GcrParser *self, 
-                                                            gconstpointer data,
+                                                            const guchar *data,
                                                             gsize n_data, 
                                                             GError **error);
 
diff --git a/gcr/gcr-pkcs11-certificate.c b/gcr/gcr-pkcs11-certificate.c
index 8e256b0..25c2207 100644
--- a/gcr/gcr-pkcs11-certificate.c
+++ b/gcr/gcr-pkcs11-certificate.c
@@ -298,8 +298,9 @@ gcr_pkcs11_certificate_class_init (GcrPkcs11CertificateClass *klass)
 	_gcr_initialize_library ();
 }
 
-static gconstpointer
-gcr_pkcs11_certificate_get_der_data (GcrCertificate *cert, gsize *n_data)
+static const guchar *
+gcr_pkcs11_certificate_get_der_data (GcrCertificate *cert,
+                                     gsize *n_data)
 {
 	GcrPkcs11Certificate *self = GCR_PKCS11_CERTIFICATE (cert);
 	GckAttribute *attr;
diff --git a/gcr/gcr-renderer.c b/gcr/gcr-renderer.c
index 5d78585..fe0386a 100644
--- a/gcr/gcr-renderer.c
+++ b/gcr/gcr-renderer.c
@@ -56,6 +56,11 @@
 
 /**
  * GcrRendererIface:
+ * @parent: the parent interface type
+ * @data_changed: signal emitted when data being rendered changes
+ * @render_view: method invoked to render the data into a viewer
+ * @populate_popup: method invoked to populate a popup menu with additional
+ *                  renderer options
  *
  * The interface for #GcrRenderer
  */
@@ -274,6 +279,12 @@ gcr_renderer_register (GType renderer_type, GckAttributes *attrs)
 	registered_sorted = FALSE;
 }
 
+/**
+ * gcr_renderer_register_well_known:
+ *
+ * Register all the well known renderers for certificates and keys known to the
+ * Gcr library.
+ */
 void
 gcr_renderer_register_well_known (void)
 {
diff --git a/gcr/gcr-simple-certificate.c b/gcr/gcr-simple-certificate.c
index eeb8254..f286c2e 100644
--- a/gcr/gcr-simple-certificate.c
+++ b/gcr/gcr-simple-certificate.c
@@ -105,8 +105,9 @@ gcr_simple_certificate_class_init (GcrSimpleCertificateClass *klass)
 	_gcr_initialize_library ();
 }
 
-static gconstpointer
-gcr_simple_certificate_get_der_data (GcrCertificate *cert, gsize *n_data)
+static const guchar *
+gcr_simple_certificate_get_der_data (GcrCertificate *cert,
+                                     gsize *n_data)
 {
 	GcrSimpleCertificate *self = GCR_SIMPLE_CERTIFICATE (cert);
 
@@ -131,7 +132,7 @@ gcr_simple_certificate_iface_init (GcrCertificateIface *iface)
 
 /**
  * gcr_simple_certificate_new:
- * @data: The raw DER certificate data
+ * @data: (array length=n_data): the raw DER certificate data
  * @n_data: The length of @data
  *
  * Create a new #GcrSimpleCertificate for the raw DER data. The @data memory is
@@ -140,7 +141,8 @@ gcr_simple_certificate_iface_init (GcrCertificateIface *iface)
  * Returns: (transfer full): a new #GcrSimpleCertificate
  */
 GcrCertificate *
-gcr_simple_certificate_new (gconstpointer data, gsize n_data)
+gcr_simple_certificate_new (const guchar *data,
+                            gsize n_data)
 {
 	GcrSimpleCertificate *cert;
 
@@ -155,8 +157,8 @@ gcr_simple_certificate_new (gconstpointer data, gsize n_data)
 }
 
 /**
- * gcr_simple_certificate_new_static:
- * @data: The raw DER certificate data
+ * gcr_simple_certificate_new_static: (skip)
+ * @data: (array length=n_data): The raw DER certificate data
  * @n_data: The length of @data
  *
  * Create a new #GcrSimpleCertificate for the raw DER data. The @data memory is
@@ -166,7 +168,8 @@ gcr_simple_certificate_new (gconstpointer data, gsize n_data)
  * Returns: (transfer full): a new #GcrSimpleCertificate
  */
 GcrCertificate *
-gcr_simple_certificate_new_static (gconstpointer data, gsize n_data)
+gcr_simple_certificate_new_static (const guchar *data,
+                                   gsize n_data)
 {
 	GcrSimpleCertificate *cert;
 
diff --git a/gcr/gcr-simple-certificate.h b/gcr/gcr-simple-certificate.h
index 79f84e1..d95aaae 100644
--- a/gcr/gcr-simple-certificate.h
+++ b/gcr/gcr-simple-certificate.h
@@ -56,10 +56,10 @@ struct _GcrSimpleCertificateClass {
 
 GType               gcr_simple_certificate_get_type               (void);
 
-GcrCertificate*     gcr_simple_certificate_new                    (gconstpointer data,
+GcrCertificate *    gcr_simple_certificate_new                    (const guchar *data,
                                                                    gsize n_data);
 
-GcrCertificate*     gcr_simple_certificate_new_static             (gconstpointer data,
+GcrCertificate *    gcr_simple_certificate_new_static             (const guchar *data,
                                                                    gsize n_data);
 
 G_END_DECLS
diff --git a/gcr/gcr-tree-selector.c b/gcr/gcr-tree-selector.c
index f44811d..fb5261f 100644
--- a/gcr/gcr-tree-selector.c
+++ b/gcr/gcr-tree-selector.c
@@ -282,7 +282,7 @@ gcr_tree_selector_class_init (GcrTreeSelectorClass *klass)
  */
 
 /**
- * gcr_tree_selector_new: (skip):
+ * gcr_tree_selector_new: (skip)
  * @collection: The collection that contains the objects to display
  * @columns: The columns to use to display the objects
  *
@@ -316,14 +316,14 @@ gcr_tree_selector_get_collection (GcrTreeSelector *self)
 }
 
 /**
- * gcr_tree_selector_get_columns: (skip):
+ * gcr_tree_selector_get_columns: (skip)
  * @self: The selector
  *
  * Get the columns displayed in a selector in multiple mode.
  *
- * Returns: The columns, owned by the selector.
+ * Returns: (transfer none): The columns, owned by the selector.
  */
-const GcrColumn*
+const GcrColumn *
 gcr_tree_selector_get_columns (GcrTreeSelector *self)
 {
 	g_return_val_if_fail (GCR_IS_TREE_SELECTOR (self), NULL);
diff --git a/gcr/gcr-types.h b/gcr/gcr-types.h
index 2fbb765..0847b1b 100644
--- a/gcr/gcr-types.h
+++ b/gcr/gcr-types.h
@@ -33,14 +33,14 @@
 #ifndef GCK_API_SUBJECT_TO_CHANGE
 
 /**
- * GCK_API_SUBJECT_TO_CHANGE: (skip):
+ * GCK_API_SUBJECT_TO_CHANGE: (skip)
  *
  * skip for gir introspection
  */
 #define GCK_API_SUBJECT_TO_CHANGE 1
 
 /**
- * __GCR_DEFINED_GCK_SUBJECT_TO_CHANGE__: (skip):
+ * __GCR_DEFINED_GCK_SUBJECT_TO_CHANGE__: (skip)
  *
  * skip for gir introspection
  */
diff --git a/gcr/gcr-viewer-widget.c b/gcr/gcr-viewer-widget.c
index c8f0028..7ed6839 100644
--- a/gcr/gcr-viewer-widget.c
+++ b/gcr/gcr-viewer-widget.c
@@ -276,6 +276,14 @@ gcr_viewer_widget_class_init (GcrViewerWidgetClass *klass)
 
 	g_type_class_add_private (klass, sizeof (GcrViewerWidget));
 
+	/**
+	 * GcrViewerWidget::added:
+	 * @self: the viewer widget
+	 * @renderer: (type Gcr.Renderer): the renderer that was added
+	 * @parsed: (type Gcr.Parsed): the parsed item that was added
+	 *
+	 * This signal is emitted when an item is added to the viewer widget.
+	 */
 	signals[ADDED] = g_signal_new ("added", GCR_TYPE_VIEWER_WIDGET, G_SIGNAL_RUN_LAST,
 	                               G_STRUCT_OFFSET (GcrViewerWidgetClass, added),
 	                               NULL, NULL, _gcr_marshal_VOID__OBJECT_BOXED,
@@ -414,10 +422,21 @@ gcr_viewer_widget_load_file (GcrViewerWidget *self,
 		viewer_load_next_file (self);
 }
 
+/**
+ * gcr_viewer_widget_load_data:
+ * @self: a viewer widget
+ * @display_name: label for the loaded data
+ * @data: (array length=n_data): data to load
+ * @n_data: length of data to load
+ *
+ * Parse and load some data to be displayed into the viewer widgets. The data
+ * may contain multiple parseable items if the format can contain multiple
+ * items.
+ */
 void
 gcr_viewer_widget_load_data (GcrViewerWidget *self,
                              const gchar *display_name,
-                             gconstpointer data,
+                             const guchar *data,
                              gsize n_data)
 {
 	GError *error = NULL;
diff --git a/gcr/gcr-viewer-widget.h b/gcr/gcr-viewer-widget.h
index 4e0b746..24b6036 100644
--- a/gcr/gcr-viewer-widget.h
+++ b/gcr/gcr-viewer-widget.h
@@ -47,7 +47,7 @@ void               gcr_viewer_widget_load_file        (GcrViewerWidget *self,
 
 void               gcr_viewer_widget_load_data        (GcrViewerWidget *self,
                                                        const gchar *display_name,
-                                                       gconstpointer data,
+                                                       const guchar *data,
                                                        gsize n_data);
 
 #endif /* GCR_VIEWER_WIDGET_H */
diff --git a/gcr/gcr-viewer-window.c b/gcr/gcr-viewer-window.c
index e2b35ca..b21bb80 100644
--- a/gcr/gcr-viewer-window.c
+++ b/gcr/gcr-viewer-window.c
@@ -147,15 +147,29 @@ gcr_viewer_window_class_init (GcrViewerWindowClass *klass)
 	g_type_class_add_private (klass, sizeof (GcrViewerWindow));
 }
 
+/**
+ * gcr_viewer_window_new:
+ *
+ * Create a new viewer window.
+ *
+ * Returns: (transfer full): a new viewer window
+ */
 GtkWindow *
 gcr_viewer_window_new (void)
 {
 	return g_object_new (GCR_TYPE_VIEWER_WINDOW, NULL);
 }
 
+/**
+ * gcr_viewer_window_load:
+ * @self: a viewer window
+ * @file: file to load
+ *
+ * Load a file into a viewer window. It may not appear immediately.
+ */
 void
 gcr_viewer_window_load (GcrViewerWindow *self,
-                         GFile *file)
+                        GFile *file)
 {
 	g_return_if_fail (GCR_IS_VIEWER_WINDOW (self));
 	g_return_if_fail (G_IS_FILE (file));
diff --git a/gcr/gcr-viewer.c b/gcr/gcr-viewer.c
index bc573ab..7f52501 100644
--- a/gcr/gcr-viewer.c
+++ b/gcr/gcr-viewer.c
@@ -118,6 +118,14 @@ gcr_viewer_add_renderer (GcrViewer *viewer,
 	GCR_VIEWER_GET_INTERFACE (viewer)->add_renderer (viewer, renderer);
 }
 
+/**
+ * gcr_viewer_insert_renderer:
+ * @viewer: the viewer
+ * @renderer: the renderer to insert
+ * @before: the renderer to insert before
+ *
+ * Insert a renderer at a specific point in the viewer
+ */
 void
 gcr_viewer_insert_renderer (GcrViewer *viewer,
                             GcrRenderer *renderer,
diff --git a/gcr/tests/frob-parser.c b/gcr/tests/frob-parser.c
index 847d56d..2459a10 100644
--- a/gcr/tests/frob-parser.c
+++ b/gcr/tests/frob-parser.c
@@ -114,7 +114,7 @@ main(int argc, char *argv[])
 			continue;
 		}
 
-		gcr_parser_parse_data (parser, contents, len, &error);
+		gcr_parser_parse_data (parser, (const guchar *)contents, len, &error);
 		g_free (contents);
 
 		if (error) {
diff --git a/gcr/tests/test-certificate-chain.c b/gcr/tests/test-certificate-chain.c
index 3bccfff..9b8735f 100644
--- a/gcr/tests/test-certificate-chain.c
+++ b/gcr/tests/test-certificate-chain.c
@@ -160,7 +160,7 @@ setup (Test *test, gconstpointer unused)
 	/* A self-signed certificate */
 	if (!g_file_get_contents (SRCDIR "/files/der-certificate.crt", &contents, &n_contents, NULL))
 		g_assert_not_reached ();
-	test->cert_self = gcr_simple_certificate_new (contents, n_contents);
+	test->cert_self = gcr_simple_certificate_new ((const guchar *)contents, n_contents);
 	g_free (contents);
 
 	/* A signed certificate */
diff --git a/gcr/tests/test-certificate.c b/gcr/tests/test-certificate.c
index dec2b52..6fb68c9 100644
--- a/gcr/tests/test-certificate.c
+++ b/gcr/tests/test-certificate.c
@@ -46,19 +46,19 @@ setup (Test *test, gconstpointer unused)
 
 	if (!g_file_get_contents (SRCDIR "/files/der-certificate.crt", &contents, &n_contents, NULL))
 		g_assert_not_reached ();
-	test->certificate = gcr_simple_certificate_new (contents, n_contents);
+	test->certificate = gcr_simple_certificate_new ((const guchar *)contents, n_contents);
 	g_assert (test->certificate);
 	g_free (contents);
 
 	if (!g_file_get_contents (SRCDIR "/files/der-certificate-dsa.cer", &contents, &n_contents, NULL))
 		g_assert_not_reached ();
-	test->dsa_cert = gcr_simple_certificate_new (contents, n_contents);
+	test->dsa_cert = gcr_simple_certificate_new ((const guchar *)contents, n_contents);
 	g_assert (test->dsa_cert);
 	g_free (contents);
 
 	if (!g_file_get_contents (SRCDIR "/files/dhansak-collabora.cer", &contents, &n_contents, NULL))
 		g_assert_not_reached ();
-	test->dhansak_cert = gcr_simple_certificate_new (contents, n_contents);
+	test->dhansak_cert = gcr_simple_certificate_new ((const guchar *)contents, n_contents);
 	g_assert (test->certificate);
 	g_free (contents);
 }
diff --git a/gcr/tests/test-parser.c b/gcr/tests/test-parser.c
index 1fa3bc1..6984be2 100644
--- a/gcr/tests/test-parser.c
+++ b/gcr/tests/test-parser.c
@@ -157,7 +157,7 @@ test_parse_one (Test *test,
 		g_assert_not_reached ();
 
 	test->filedesc = path;
-	result = gcr_parser_parse_data (test->parser, contents, len, &error);
+	result = gcr_parser_parse_data (test->parser, (const guchar *)contents, len, &error);
 	g_assert_no_error (error);
 	g_assert (result);
 
@@ -186,7 +186,7 @@ test_parse_empty (void)
 	GError *error = NULL;
 	gboolean result;
 
-	result = gcr_parser_parse_data (parser, "", 0, &error);
+	result = gcr_parser_parse_data (parser, (const guchar *)"", 0, &error);
 	g_assert_error (error, GCR_DATA_ERROR, GCR_ERROR_UNRECOGNIZED);
 	g_assert (!result);
 	g_error_free (error);
diff --git a/gcr/tests/test-trust.c b/gcr/tests/test-trust.c
index 1071509..d41596c 100644
--- a/gcr/tests/test-trust.c
+++ b/gcr/tests/test-trust.c
@@ -58,7 +58,7 @@ setup (Test *test, gconstpointer unused)
 		g_assert_not_reached ();
 	g_assert (contents);
 
-	test->certificate = gcr_simple_certificate_new (contents, len);
+	test->certificate = gcr_simple_certificate_new ((const guchar *)contents, len);
 	g_free (contents);
 
 	rv = gck_mock_C_GetFunctionList (&f);
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]