From a336ded87ffc9166e67adc008b7b11f4d2d283a5 Mon Sep 17 00:00:00 2001
From: Stefan Walter <stefw@src.gnome.org>
Date: Sun, 31 Aug 2008 20:16:23 +0000
Subject: [PATCH] Complete some more documentation.

	* gp11/gp11-misc.c:
	* gp11/gp11-module.c: Complete some more documentation.

svn path=/trunk/; revision=1284
---
 gp11/gp11-misc.c   | 37 ++++++++++++++++++++++++++++++++++++-
 gp11/gp11-module.c | 24 ++++++++++++++++++++++++
 2 files changed, 60 insertions(+), 1 deletion(-)

diff --git a/gp11/gp11-misc.c b/gp11/gp11-misc.c
index 90b32e6..0d1c10e 100644
--- a/gp11/gp11-misc.c
+++ b/gp11/gp11-misc.c
@@ -27,6 +27,13 @@
 
 #include <glib/gi18n.h>
 
+/**
+ * gp11_get_error_quark:
+ *
+ * The error domain for GP11 library errors.
+ *
+ * Return value: The error domain.
+ */
 GQuark
 gp11_get_error_quark (void)
 {
@@ -36,6 +43,13 @@ gp11_get_error_quark (void)
 	return domain;
 }
 
+/**
+ * gp11_list_unref_free:
+ * reflist: List of Gobject reference counted pointers.
+ *
+ * Free a list of GObject based pointers. All objects in the list
+ * will be unreffed and then the list itself will be freed.
+ */
 void
 gp11_list_unref_free (GList *reflist)
 {
@@ -47,6 +61,15 @@ gp11_list_unref_free (GList *reflist)
 	g_list_free (reflist);
 }
 
+/**
+ * gp11_message_from_rv:
+ * rv: The PKCS#11 return value to get a message for.
+ *
+ * Get a message for a PKCS#11 return value or error code. Do not
+ * pass CKR_OK or other such non errors to this function.
+ *
+ * Return value: The user readable message.
+ */
 const gchar*
 gp11_message_from_rv (CK_RV rv)
 {
@@ -228,6 +251,18 @@ gp11_message_from_rv (CK_RV rv)
 	}
 }
 
+/**
+ * gp11_string_form_chars:
+ * @data: The character data to turn into a null terminated string.
+ * @max: The maximum length of the charater data.
+ *
+ * Create a string from a set of PKCS#11 characters. This is
+ * similar to g_strndup, except for that it also strips trailing
+ * spaces. These space padded strings are often used in PKCS#11
+ * structures.
+ *
+ * Return value: The null terminated string.
+ */
 gchar*
 gp11_string_from_chars (const guchar *data, gsize max)
 {
@@ -237,6 +272,6 @@ gp11_string_from_chars (const guchar *data, gsize max)
 	g_return_val_if_fail (max, NULL);
 
 	string = g_strndup ((gchar*)data, max);
-	g_strstrip (string);
+	g_strchomp (string);
 	return string;
 }
diff --git a/gp11/gp11-module.c b/gp11/gp11-module.c
index 095c82a..cd37a21 100644
--- a/gp11/gp11-module.c
+++ b/gp11/gp11-module.c
@@ -187,6 +187,12 @@ gp11_module_class_init (GP11ModuleClass *klass)
  * PUBLIC
  */
 
+/**
+ * gp11_module_info_free:
+ * @module_info: The module info to free, or NULL.
+ *
+ * Free a GP11ModuleInfo structure.
+ **/
 void
 gp11_module_info_free (GP11ModuleInfo *module_info)
 {
@@ -197,6 +203,16 @@ gp11_module_info_free (GP11ModuleInfo *module_info)
 	g_free (module_info);
 }
 
+/**
+ * gp11_module_initialize:
+ * @path: The file system path to the PKCS#11 module to load.
+ * @reserved: Extra arguments for the PKCS#11 module, should usually be NULL.
+ * @err: A location to store an error resulting from a failed load.
+ *
+ * Load and initialize a PKCS#11 module represented by a GP11Module object.
+ *
+ * Return value: The loaded PKCS#11 module or NULL if failed.
+ **/
 GP11Module*
 gp11_module_initialize (const gchar *path, gpointer reserved, GError **err)
 {
@@ -268,6 +284,14 @@ gp11_module_initialize (const gchar *path, gpointer reserved, GError **err)
 	return mod;
 }
 
+/**
+ * gp11_module_get_info:
+ * @module: The module to get info for.
+ *
+ * Get the info about a PKCS#11 module.
+ *
+ * Return value: The module info. Release this with gp11_module_info_free().
+ **/
 GP11ModuleInfo*
 gp11_module_get_info (GP11Module *module)
 {
-- 
2.7.4