[gnome-keyring] [doc] Fix up documentation errors and warnings.
- From: Stefan Walter <stefw src gnome org>
- To: svn-commits-list gnome org
- Cc:
- Subject: [gnome-keyring] [doc] Fix up documentation errors and warnings.
- Date: Thu, 17 Dec 2009 05:33:22 +0000 (UTC)
commit dad18054f95e9484071bad2b130a062729e662df
Author: Stef Walter <stef memberwebs com>
Date: Thu Dec 17 05:31:05 2009 +0000
[doc] Fix up documentation errors and warnings.
gcr/gcr-certificate.c | 18 +++++++++---------
gp11/gp11-attributes.c | 46 ++++++++++++++++++++++++++++------------------
gp11/gp11-misc.c | 12 ++++++------
gp11/gp11-module.c | 21 +++++++++------------
gp11/gp11-object.c | 8 ++++----
gp11/gp11-session.c | 4 ++--
gp11/gp11-slot.c | 1 +
gp11/gp11.h | 43 ++++++++++++++++++-------------------------
8 files changed, 77 insertions(+), 76 deletions(-)
---
diff --git a/gcr/gcr-certificate.c b/gcr/gcr-certificate.c
index c16c6a1..d4a36bd 100644
--- a/gcr/gcr-certificate.c
+++ b/gcr/gcr-certificate.c
@@ -267,13 +267,13 @@ gcr_certificate_get_type (void)
* Gets the raw DER data for an X509 certificate.
*
* Returns: raw DER data of the X509 certificate.
- */
+ **/
const guchar*
-gcr_certificate_get_der_data (GcrCertificate *self, gsize *n_length)
+gcr_certificate_get_der_data (GcrCertificate *self, gsize *n_data)
{
g_return_val_if_fail (GCR_IS_CERTIFICATE (self), NULL);
g_return_val_if_fail (GCR_CERTIFICATE_GET_INTERFACE (self)->get_der_data, NULL);
- return GCR_CERTIFICATE_GET_INTERFACE (self)->get_der_data (self, n_length);
+ return GCR_CERTIFICATE_GET_INTERFACE (self)->get_der_data (self, n_data);
}
/**
@@ -509,7 +509,7 @@ gcr_certificate_get_key_size (GcrCertificate *self)
* gcr_certificate_get_fingerprint:
* @self: a #GcrCertificate
* @type: the type of algorithm for the fingerprint.
- * @n_digest: The length of the resulting fingerprint.
+ * @n_length: The length of the resulting fingerprint.
*
* Calculate the fingerprint for this certificate.
*
@@ -520,24 +520,24 @@ gcr_certificate_get_key_size (GcrCertificate *self)
* it is no longer required.
*
* Returns: the raw binary fingerprint.
- */
+ **/
guchar*
-gcr_certificate_get_fingerprint (GcrCertificate *self, GChecksumType type, gsize *n_digest)
+gcr_certificate_get_fingerprint (GcrCertificate *self, GChecksumType type, gsize *n_length)
{
GChecksum *sum;
guchar *digest;
gssize length;
g_return_val_if_fail (GCR_IS_CERTIFICATE (self), NULL);
- g_return_val_if_fail (n_digest, NULL);
+ g_return_val_if_fail (n_length, NULL);
sum = digest_certificate (self, type);
g_return_val_if_fail (sum, NULL);
length = g_checksum_type_get_length (type);
g_return_val_if_fail (length > 0, NULL);
digest = g_malloc (length);
- *n_digest = length;
- g_checksum_get_digest (sum, digest, n_digest);
+ *n_length = length;
+ g_checksum_get_digest (sum, digest, n_length);
g_checksum_free (sum);
return digest;
diff --git a/gp11/gp11-attributes.c b/gp11/gp11-attributes.c
index 5917902..391a537 100644
--- a/gp11/gp11-attributes.c
+++ b/gp11/gp11-attributes.c
@@ -653,34 +653,39 @@ struct _GP11Attributes {
/**
* GP11_BOOLEAN:
+ *
* The attribute data is a gboolean. Used with variable argument functions.
- */
+ **/
/**
* GP11_ULONG:
+ *
* The attribute data is a gulong. Used with variable argument functions.
- */
+ **/
/**
* GP11_STRING:
+ *
* The attribute data is a gchar. Used with variable argument functions.
- */
+ **/
/**
* GP11_DATE:
+ *
* The attribute data is a GDate. Used with variable argument functions.
- */
+ **/
/**
* GP11_DATE:
+ *
* Signifies that no more attributes follow. Used with variable argument functions.
- */
+ **/
/**
* GP11_ATTRIBUTES_TYPE:
*
* A boxed type that can be used to hold a GP11Attributes object.
- */
+ **/
/**
* GP11Allocator:
@@ -691,8 +696,10 @@ struct _GP11Attributes {
*
* This is a function that acts like g_realloc. Specifically it frees when length is
* set to zero, it allocates when data is set to NULL, and it reallocates when both
- * are valid.
- */
+ * are valid.
+ *
+ * Returns: The allocated memory, or NULL when freeing.
+ **/
/**
* gp11_attributes_get_boxed_type:
@@ -755,9 +762,10 @@ gp11_attributes_new_full (GP11Allocator allocator)
/**
* gp11_attributes_new_empty:
* @attr_type: The first attribute type to add as empty.
+ * @...: The arguments should be values of attribute types, terminated with GP11_INVALID.
*
* Creates an GP11Attributes array with empty attributes. The arguments
- * should be values of attribute types, terminated with -1.
+ * should be values of attribute types, terminated with GP11_INVALID.
*
* Return value: The new attributes array. When done with the array
* release it with gp11_attributes_unref().
@@ -834,11 +842,11 @@ initialize_from_valist (GP11Allocator allocator, gulong type, va_list va)
/**
* gp11_attributes_newv:
- *
+ * @attr_type: The first attribute type.
+ * @...: The arguments must be triples of: attribute type, data type, value
+ *
* Create a new GP11Attributes array, containing a list of attributes.
*
- * The arguments must be triples of: attribute type, data type, value
- *
* <para>The variable argument list should contain:
* <variablelist>
* <varlistentry>
@@ -862,20 +870,20 @@ initialize_from_valist (GP11Allocator allocator, gulong type, va_list va)
* release it with gp11_attributes_unref().
**/
GP11Attributes*
-gp11_attributes_newv (gulong first_type, ...)
+gp11_attributes_newv (gulong attr_type, ...)
{
GP11Attributes *attrs;
va_list va;
- va_start (va, first_type);
- attrs = initialize_from_valist (g_realloc, first_type, va);
+ va_start (va, attr_type);
+ attrs = initialize_from_valist (g_realloc, attr_type, va);
va_end (va);
return attrs;
}
/**
- * gp11_attributes_newv:
+ * gp11_attributes_new_valist:
* @allocator: Memory allocator for attribute data, or NULL for default.
* @va: Variable argument containing attributes to add.
*
@@ -1289,9 +1297,11 @@ gp11_attributes_find_date (GP11Attributes *attrs, gulong attr_type, GDate *value
/**
* gp11_attributes_ref:
* @attrs: An attribute array
- *
+ *
* Reference this attributes array.
- */
+ *
+ * Returns: The attributes.
+ **/
GP11Attributes*
gp11_attributes_ref (GP11Attributes *attrs)
{
diff --git a/gp11/gp11-misc.c b/gp11/gp11-misc.c
index 35fa958..7457042 100644
--- a/gp11/gp11-misc.c
+++ b/gp11/gp11-misc.c
@@ -74,13 +74,13 @@ gp11_get_error_quark (void)
/**
* gp11_message_from_rv:
- * rv: The PKCS#11 return value to get a message for.
+ * @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)
{
@@ -273,11 +273,11 @@ gp11_message_from_rv (CK_RV rv)
/**
* gp11_list_unref_free:
- * reflist: List of Gobject reference counted pointers.
+ * @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)
{
@@ -291,14 +291,14 @@ gp11_list_unref_free (GList *reflist)
/**
* gp11_list_ref_copy:
- * reflist: List of GObject reference counted objects.
+ * @reflist: List of GObject reference counted objects.
*
* Copy a list of GObject based pointers. All objects
* in the list will be reffed and the list will be copied.
*
* Return value: The copied and reffed list. When done, free it with
* gp11_list_unref_free ()
- */
+ **/
GList*
gp11_list_ref_copy (GList *reflist)
{
diff --git a/gp11/gp11-module.c b/gp11/gp11-module.c
index 359b1b3..3fb3faa 100644
--- a/gp11/gp11-module.c
+++ b/gp11/gp11-module.c
@@ -761,9 +761,7 @@ gp11_module_initialize (const gchar *path, gpointer reserved, GError **err)
/**
* gp11_module_new:
* @funcs: Initialized PKCS#11 function list pointer
- * @reserved: Extra arguments for the PKCS#11 module, should usually be NULL.
- * @err: A location to store an error resulting from a failed load.
- *
+ *
* Create a GP11Module representing a PKCS#11 module. It is assumed that
* this the module is already initialized. In addition it will not be
* finalized when complete.
@@ -978,7 +976,7 @@ gp11_module_get_pool_sessions (GP11Module *self)
/**
* gp11_module_set_pool_sessions:
* @self: The module to set the setting on.
- * @reuse: Whether to reuse sessions or not.
+ * @pool: Whether to reuse sessions or not.
*
* When this is set, sessions will be pooled and reused
* if their flags match when gp11_slot_open_session() is called.
@@ -1032,7 +1030,7 @@ gp11_module_get_auto_authenticate (GP11Module *self)
/**
* gp11_module_set_auto_authenticate:
* @self: The module to set the setting on.
- * @auto_login: Whether auto login or not.
+ * @auto_authenticate: Whether auto login or not.
*
* When this is set, this slot
* will emit the 'authenticate-slot' signal when a session
@@ -1040,18 +1038,18 @@ gp11_module_get_auto_authenticate (GP11Module *self)
* signal when an object requires authintication.
**/
void
-gp11_module_set_auto_authenticate (GP11Module *self, gint auto_login)
+gp11_module_set_auto_authenticate (GP11Module *self, gint auto_authenticate)
{
GP11ModulePrivate *pv = lock_private (self);
/* HACK: Get needed fix around API freeze. */
- if (auto_login == 1)
- auto_login = GP11_AUTHENTICATE_TOKENS | GP11_AUTHENTICATE_OBJECTS;
+ if (auto_authenticate == 1)
+ auto_authenticate = GP11_AUTHENTICATE_TOKENS | GP11_AUTHENTICATE_OBJECTS;
g_return_if_fail (pv);
{
- pv->auto_authenticate = auto_login;
+ pv->auto_authenticate = auto_authenticate;
}
unlock_private (self, pv);
@@ -1061,14 +1059,13 @@ gp11_module_set_auto_authenticate (GP11Module *self, gint auto_login)
/**
* gp11_module_enumerate_objects:
* @self: The module to enumerate objects.
- * @attrs: Attributes that the objects must have, or empty for all objects.
* @func: Function to call for each object.
* @user_data: Data to pass to the function.
- *
+ * @...: The arguments must be triples of: attribute type, data type, value.
+ *
* Call a function for every matching object on the module. This call may
* block for an indefinite period.
*
- * The arguments must be triples of: attribute type, data type, value
*
* <para>The variable argument list should contain:
* <variablelist>
diff --git a/gp11/gp11-object.c b/gp11/gp11-object.c
index 3bcfe75..7fa08f8 100644
--- a/gp11/gp11-object.c
+++ b/gp11/gp11-object.c
@@ -669,7 +669,7 @@ free_set_attributes (SetAttributes *args)
* gp11_object_set:
* @self: The object to set attributes on.
* @err: A location to return an error.
- * ...: The attributes to set.
+ * @...: The attributes to set.
*
* Set PKCS#11 attributes on an object.
* This call may block for an indefinite period.
@@ -893,8 +893,8 @@ free_get_attributes (GetAttributes *args)
* gp11_object_get:
* @self: The object to get attributes from.
* @err: A location to store an error.
- * ...: The attribute types to get.
- *
+ * @...: The attribute types to get.
+ *
* Get the specified attributes from the object. This call may
* block for an indefinite period.
*
@@ -930,7 +930,7 @@ gp11_object_get (GP11Object *self, GError **err, ...)
}
/**
- * gp11_object_get:
+ * gp11_object_get_full:
* @self: The object to get attributes from.
* @attrs: The attributes to get, with the types filled in.
* @cancellable: Optional cancellation object, or NULL.
diff --git a/gp11/gp11-session.c b/gp11/gp11-session.c
index f03bfa9..6ebd881 100644
--- a/gp11/gp11-session.c
+++ b/gp11/gp11-session.c
@@ -934,7 +934,7 @@ perform_create_object (CreateObject *args)
* gp11_session_create_object:
* @self: The session to create the object on.
* @err: A location to store an error.
- * ...: The attributes to create the new object with.
+ * @...: The attributes to create the new object with.
*
* Create a new PKCS#11 object. This call may block
* for an indefinite period.
@@ -1157,7 +1157,7 @@ objlist_from_handles (GP11Session *self, CK_OBJECT_HANDLE_PTR objects,
* gp11_session_find_objects:
* @self: The session to find objects on.
* @err: A location to return an error or NULL.
- * ...: The attributes to match.
+ * @...: The attributes to match.
*
* Find objects matching the passed attributes. This call may
* block for an indefinite period.
diff --git a/gp11/gp11-slot.c b/gp11/gp11-slot.c
index 2c1ebcf..2ca2af5 100644
--- a/gp11/gp11-slot.c
+++ b/gp11/gp11-slot.c
@@ -375,6 +375,7 @@ gp11_mechanism_info_free (GP11MechanismInfo *mech_info)
/**
* gp11_mechanisms_check:
* @mechanisms: A list of mechanisms, perhaps retrieved from gp11_slot_get_mechanisms().
+ * @...: A list of mechanism types followed by GP11_INVALID.
*
* Check whether all the mechanism types are in the list.
*
diff --git a/gp11/gp11.h b/gp11/gp11.h
index f7c69d3..1e4b8b2 100644
--- a/gp11/gp11.h
+++ b/gp11/gp11.h
@@ -90,13 +90,6 @@ enum {
GP11_AUTHENTICATE_OBJECTS = 4
};
-/* Used on varargs functions that should end with GP11_INVALID */
-#ifdef NOT_YET_SUPPORTED
-#define GP11_INVALID_TERMINATED __attribute__((__sentinel__(G_MAXULONG)))
-#else
-#define GP11_INVALID_TERMINATED
-#endif
-
void gp11_attribute_init (GP11Attribute *attr,
gulong attr_type,
gconstpointer value,
@@ -174,12 +167,12 @@ GType gp11_attributes_get_boxed_type (void) G_GNUC_CONST;
GP11Attributes* gp11_attributes_new (void);
GP11Attributes* gp11_attributes_new_empty (gulong attr_type,
- ...) GP11_INVALID_TERMINATED;
+ ...);
GP11Attributes* gp11_attributes_new_full (GP11Allocator allocator);
GP11Attributes* gp11_attributes_newv (gulong attr_type,
- ...) GP11_INVALID_TERMINATED;
+ ...);
GP11Attributes* gp11_attributes_new_valist (GP11Allocator allocator,
va_list va);
@@ -207,11 +200,11 @@ GP11Attribute* gp11_attributes_add_boolean (GP11Attributes *att
GP11Attribute* gp11_attributes_add_string (GP11Attributes *attrs,
gulong attr_type,
- const gchar *string);
+ const gchar *value);
GP11Attribute* gp11_attributes_add_date (GP11Attributes *attrs,
gulong attr_type,
- const GDate *date);
+ const GDate *value);
GP11Attribute* gp11_attributes_add_ulong (GP11Attributes *attrs,
gulong attr_type,
@@ -319,7 +312,7 @@ GList* gp11_module_get_slots (GP11Module *self,
gboolean gp11_module_get_pool_sessions (GP11Module *self);
void gp11_module_set_pool_sessions (GP11Module *self,
- gboolean pool_sessions);
+ gboolean pool);
gint gp11_module_get_auto_authenticate (GP11Module *self);
@@ -329,7 +322,7 @@ void gp11_module_set_auto_authenticate (GP11Module *self,
gboolean gp11_module_enumerate_objects (GP11Module *self,
GP11ObjectForeachFunc func,
gpointer user_data,
- ...) GP11_INVALID_TERMINATED;
+ ...);
gboolean gp11_module_enumerate_objects_full (GP11Module *self,
GP11Attributes *attrs,
@@ -686,7 +679,7 @@ gboolean gp11_session_logout_finish (GP11Session *self,
GP11Object* gp11_session_create_object (GP11Session *self,
GError **err,
- ...) GP11_INVALID_TERMINATED;
+ ...);
GP11Object* gp11_session_create_object_full (GP11Session *self,
GP11Attributes *attrs,
@@ -705,7 +698,7 @@ GP11Object* gp11_session_create_object_finish (GP11Session *self,
GList* gp11_session_find_objects (GP11Session *self,
GError **err,
- ...) GP11_INVALID_TERMINATED;
+ ...);
GList* gp11_session_find_objects_full (GP11Session *self,
GP11Attributes *attrs,
@@ -727,18 +720,18 @@ GList* gp11_session_find_objects_finish (GP11Session *self,
GP11Object* gp11_session_generate_key (GP11Session *self,
GP11Mechanism *mechanism,
GError **err,
- ...) GP11_INVALID_TERMINATED;
+ ...);
void gp11_session_generate_key_async (GP11Session *self,
GP11Mechanism *mechanism,
GAsyncReadyCallback callback,
gpointer user_data,
- ...) GP11_INVALID_TERMINATED;
+ ...);
GP11Object* gp11_session_generate_key_finish (GP11Session *self,
GAsyncResult *result,
GError **err,
- ...) GP11_INVALID_TERMINATED;
+ ...);
#endif /* UNIMPLEMENTED */
@@ -1229,7 +1222,7 @@ GP11Object* gp11_session_unwrap_key (GP11Session *self,
gconstpointer input,
gsize n_input,
GError **err,
- ...) GP11_INVALID_TERMINATED;
+ ...);
GP11Object* gp11_session_unwrap_key_full (GP11Session *self,
GP11Object *wrapper,
@@ -1258,7 +1251,7 @@ GP11Object* gp11_session_derive_key (GP11Session *self,
GP11Object *base,
gulong mech_type,
GError **err,
- ...) GP11_INVALID_TERMINATED;
+ ...);
GP11Object* gp11_session_derive_key_full (GP11Session *self,
GP11Object *base,
@@ -1311,10 +1304,10 @@ GList* gp11_objects_from_handle_array (GP11Slot *slot,
CK_OBJECT_HANDLE_PTR handles,
CK_ULONG n_handles);
-gboolean gp11_object_equal (gconstpointer slot1,
- gconstpointer slot2);
+gboolean gp11_object_equal (gconstpointer object1,
+ gconstpointer object2);
-guint gp11_object_hash (gconstpointer slot);
+guint gp11_object_hash (gconstpointer object);
GP11Module* gp11_object_get_module (GP11Object *self);
@@ -1386,7 +1379,7 @@ gssize gp11_object_get_size_finish (GP11Object *self,
gboolean gp11_object_set (GP11Object *self,
GError **err,
- ...) GP11_INVALID_TERMINATED;
+ ...);
gboolean gp11_object_set_full (GP11Object *self,
GP11Attributes *attrs,
@@ -1405,7 +1398,7 @@ gboolean gp11_object_set_finish (GP11Object *self,
GP11Attributes* gp11_object_get (GP11Object *self,
GError **err,
- ...) GP11_INVALID_TERMINATED;
+ ...);
GP11Attributes* gp11_object_get_full (GP11Object *self,
GP11Attributes *attrs,
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
