Documentation fixes and cleanups.

6 files changed, 80 insertions, 18 deletions

diff --git a/lib/gnutls_pubkey.c b/lib/gnutls_pubkey.c
index 0e788b2c49..0075f3917c 100644
--- a/lib/gnutls_pubkey.c
+++ b/lib/gnutls_pubkey.c
@@ -203,7 +203,7 @@ gnutls_pubkey_import_x509 (gnutls_pubkey_t key, gnutls_x509_crt_t crt,
 }
 
 /**
- * gnutls_pubkey_import_privkey:
+ * gnutls_pubkey_import_privkey: Imports the public key from a private
  * @key: The public key
  * @pkey: The private key
  * @usage: GNUTLS_KEY_* key usage flags.
@@ -268,7 +268,7 @@ gnutls_pubkey_get_preferred_hash_algorithm (gnutls_pubkey_t key,
 
 
 /**
- * gnutls_pubkey_import_pkcs11:
+ * gnutls_pubkey_import_pkcs11: Imports a public key from a pkcs11 key
  * @key: The public key
  * @obj: The parameters to be imported
  * @flags: should be zero
@@ -321,7 +321,7 @@ gnutls_pubkey_import_pkcs11 (gnutls_pubkey_t key,
 
 #ifdef ENABLE_OPENPGP
 /**
- * gnutls_pubkey_import_openpgp:
+ * gnutls_pubkey_import_openpgp: Imports a public key from an openpgp key
  * @key: The public key
  * @crt: The certificate to be imported
  * @flags: should be zero
@@ -823,7 +823,7 @@ gnutls_x509_crq_set_pubkey (gnutls_x509_crq_t crq, gnutls_pubkey_t key)
 
 /**
  * gnutls_pubkey_set_key_usage:
- * @crt: a certificate of type #gnutls_x509_crt_t
+ * @key: a certificate of type #gnutls_x509_crt_t
  * @usage: an ORed sequence of the GNUTLS_KEY_* elements.
  *
  * This function will set the key usage flags of the public key. This
diff --git a/lib/includes/gnutls/pkcs11.h b/lib/includes/gnutls/pkcs11.h
index 5f6be2e834..0b9b2f27c8 100644
--- a/lib/includes/gnutls/pkcs11.h
+++ b/lib/includes/gnutls/pkcs11.h
@@ -19,7 +19,15 @@ typedef int (*gnutls_pkcs11_token_callback_t) (void *const global_data,
                                                const char *const label,
                                                const unsigned retry);
 
-/* flags */
+  /**
+   * gnutls_pkcs11_pin_flag_t:
+   * @GNUTLS_PKCS11_PIN_USER: The PIN for the user.
+   * @GNUTLS_PKCS11_PIN_SO: The PIN for the security officer.
+   * @GNUTLS_PKCS11_PIN_FINAL_TRY: This is the final try before blocking.
+   * @GNUTLS_PKCS11_PIN_COUNT_LOW: Few tries remain before token blocks.
+   *
+   * Enumeration of different PIN flags.
+   */
 typedef enum
 {
   GNUTLS_PKCS11_PIN_USER = (1 << 0),
@@ -60,6 +68,14 @@ int gnutls_pkcs11_obj_init (gnutls_pkcs11_obj_t * certificate);
 #define GNUTLS_PKCS11_OBJ_FLAG_MARK_TRUSTED (1<<1)      /* object marked as trusted */
 #define GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE (1<<2)    /* object marked as sensitive (unexportable) */
 
+  /**
+   * gnutls_pkcs11_url_type_t:
+   * @GNUTLS_PKCS11_URL_GENERIC: A generic-purpose URL.
+   * @GNUTLS_PKCS11_URL_LIB: A URL that specifies the library used as well.
+   * @GNUTLS_PKCS11_URL_LIB_VERSION: A URL that specifies the library and its version.
+   *
+   * Enumeration of different URL extraction flags.
+   */
 typedef enum
 {
   GNUTLS_PKCS11_URL_GENERIC,    /* URL specifies the object on token level */
@@ -94,6 +110,21 @@ int gnutls_pkcs11_copy_secret_key (const char *token_url,
                                    unsigned int flags
                                    /* GNUTLS_PKCS11_OBJ_FLAG_* */ );
 
+  /**
+   * gnutls_pkcs11_obj_info_t:
+   * @GNUTLS_PKCS11_OBJ_ID_HEX: The object ID in hex.
+   * @GNUTLS_PKCS11_OBJ_LABEL: The object label.
+   * @GNUTLS_PKCS11_OBJ_TOKEN_LABEL: The token's label.
+   * @GNUTLS_PKCS11_OBJ_TOKEN_SERIAL: The token's serial number.
+   * @GNUTLS_PKCS11_OBJ_TOKEN_MANUFACTURER: The token's manufacturer.
+   * @GNUTLS_PKCS11_OBJ_TOKEN_MODEL: The token's model.
+   * @GNUTLS_PKCS11_OBJ_ID: The object ID.
+   * @GNUTLS_PKCS11_OBJ_LIBRARY_VERSION: The library's used to access the object version.
+   * @GNUTLS_PKCS11_OBJ_LIBRARY_DESCRIPTION: The library's used to access the object description (name).
+   * @GNUTLS_PKCS11_OBJ_LIBRARY_MANUFACTURER: The library's used to access the object manufacturer name.
+   *
+   * Enumeration of several object information types.
+   */
 typedef enum
 {
   GNUTLS_PKCS11_OBJ_ID_HEX = 1,
@@ -113,6 +144,17 @@ int gnutls_pkcs11_obj_get_info (gnutls_pkcs11_obj_t crt,
                                 gnutls_pkcs11_obj_info_t itype, void *output,
                                 size_t * output_size);
 
+  /**
+   * gnutls_pkcs11_obj_attr_t:
+   * @GNUTLS_PKCS11_OBJ_ATTR_CRT_ALL: Specify all certificates.
+   * @GNUTLS_PKCS11_OBJ_ATTR_CRT_TRUSTED: Specify all certificates marked as trusted.
+   * @GNUTLS_PKCS11_OBJ_ATTR_CRT_WITH_PRIVKEY: Specify all certificates with a corresponding private key.
+   * @GNUTLS_PKCS11_OBJ_ATTR_PUBKEY: Specify all public keys.
+   * @GNUTLS_PKCS11_OBJ_ATTR_PRIVKEY: Specify all private keys.
+   * @GNUTLS_PKCS11_OBJ_ATTR_ALL: Specify all objects.
+   *
+   * Enumeration of several attributes for object enumeration.
+   */
 typedef enum
 {
   GNUTLS_PKCS11_OBJ_ATTR_CRT_ALL = 1,   /* all certificates */
@@ -123,7 +165,15 @@ typedef enum
   GNUTLS_PKCS11_OBJ_ATTR_ALL    /* everything! */
 } gnutls_pkcs11_obj_attr_t;
 
-/* token info */
+  /**
+   * gnutls_pkcs11_token_info_t:
+   * @GNUTLS_PKCS11_TOKEN_LABEL: The token's label
+   * @GNUTLS_PKCS11_TOKEN_SERIAL: The token's serial number
+   * @GNUTLS_PKCS11_TOKEN_MANUFACTURER: The token's manufacturer
+   * @GNUTLS_PKCS11_TOKEN_MODEL: The token's model
+   *
+   * Enumeration of types for retrieving token information.
+   */
 typedef enum
 {
   GNUTLS_PKCS11_TOKEN_LABEL,
@@ -132,6 +182,17 @@ typedef enum
   GNUTLS_PKCS11_TOKEN_MODEL
 } gnutls_pkcs11_token_info_t;
 
+  /**
+   * gnutls_pkcs11_obj_type_t:
+   * @GNUTLS_PKCS11_OBJ_UNKNOWN: Unknown PKCS11 object.
+   * @GNUTLS_PKCS11_OBJ_X509_CRT: X.509 certificate.
+   * @GNUTLS_PKCS11_OBJ_PUBKEY: Public key.
+   * @GNUTLS_PKCS11_OBJ_PRIVKEY: Private key.
+   * @GNUTLS_PKCS11_OBJ_SECRET_KEY: Secret key.
+   * @GNUTLS_PKCS11_OBJ_DATA: Data object.
+   *
+   * Enumeration of object types.
+   */
 typedef enum
 {
   GNUTLS_PKCS11_OBJ_UNKNOWN,
diff --git a/lib/pkcs11.c b/lib/pkcs11.c
index 06242e2c0d..bec2d16726 100644
--- a/lib/pkcs11.c
+++ b/lib/pkcs11.c
@@ -940,15 +940,15 @@ gnutls_pkcs11_obj_init (gnutls_pkcs11_obj_t * crt)
 
 /**
  * gnutls_pkcs11_obj_deinit:
- * @key: The structure to be initialized
+ * @obj: The structure to be initialized
  *
  * This function will deinitialize a certificate structure.
  **/
 void
-gnutls_pkcs11_obj_deinit (gnutls_pkcs11_obj_t crt)
+gnutls_pkcs11_obj_deinit (gnutls_pkcs11_obj_t obj)
 {
-  _gnutls_free_datum (&crt->raw);
-  free (crt);
+  _gnutls_free_datum (&obj->raw);
+  free (obj);
 }
 
 /**
@@ -1921,7 +1921,7 @@ gnutls_pkcs11_token_get_url (unsigned int seq,
 /**
  * gnutls_pkcs11_token_get_info:
  * @url: should contain a PKCS 11 URL
- * @itype: Denotes the type of information requested
+ * @ttype: Denotes the type of information requested
  * @output: where output will be stored
  * @output_size: contains the maximum size of the output and will be overwritten with actual
  *
@@ -2669,7 +2669,7 @@ cleanup:
 /**
  * gnutls_x509_crt_import_pkcs11:
  * @crt: A certificate of type #gnutls_x509_crt_t
- * @pkcs11_obj: A PKCS 11 object that contains a certificate
+ * @pkcs11_crt: A PKCS 11 object that contains a certificate
  *
  * This function will import a PKCS 11 certificate to a #gnutls_x509_crt_t
  * structure.
@@ -2686,7 +2686,7 @@ gnutls_x509_crt_import_pkcs11 (gnutls_x509_crt_t crt,
 
 /**
  * gnutls_x509_crt_list_import_pkcs11:
- * @cert: A list of certificates of type #gnutls_x509_crt_t
+ * @certs: A list of certificates of type #gnutls_x509_crt_t
  * @cert_max: The maximum size of the list
  * @objs: A list of PKCS 11 objects
  * @flags: 0 for now
diff --git a/lib/pkcs11_privkey.c b/lib/pkcs11_privkey.c
index 9cbd3c024d..7842f06c07 100644
--- a/lib/pkcs11_privkey.c
+++ b/lib/pkcs11_privkey.c
@@ -93,7 +93,7 @@ gnutls_pkcs11_privkey_get_pk_algorithm (gnutls_pkcs11_privkey_t key,
 
 /**
  * gnutls_pkcs11_privkey_get_info:
- * @key: should contain a #gnutls_pkcs11_privkey_t structure
+ * @pkey: should contain a #gnutls_pkcs11_privkey_t structure
  * @itype: Denotes the type of information requested
  * @output: where output will be stored
  * @output_size: contains the maximum size of the output and will be overwritten with actual
diff --git a/lib/pkcs11_secret.c b/lib/pkcs11_secret.c
index 6505d4dd51..3cfb1e161b 100644
--- a/lib/pkcs11_secret.c
+++ b/lib/pkcs11_secret.c
@@ -30,10 +30,9 @@
 #include <random.h>
 
 /**
- * gnutls_pkcs11_copy_x509_crt:
+ * gnutls_pkcs11_copy_secret_key:
  * @token_url: A PKCS #11 URL specifying a token
  * @key: The raw key
- * @key_size: the size of the key
  * @label: A name to be used for the stored data
  * @key_usage: One of GNUTLS_KEY_*
  * @flags: One of GNUTLS_PKCS11_OBJ_FLAG_*
diff --git a/lib/x509/privkey.c b/lib/x509/privkey.c
index c039f01d63..8443e3f8cf 100644
--- a/lib/x509/privkey.c
+++ b/lib/x509/privkey.c
@@ -507,6 +507,8 @@ gnutls_x509_privkey_import_rsa_raw (gnutls_x509_privkey_t key,
  * @p: holds the first prime (p)
  * @q: holds the second prime (q)
  * @u: holds the coefficient
+ * @e1: holds e1 = d mod (p-1)
+ * @e2: holds e2 = d mod (q-1)
  *
  * This function will convert the given RSA raw parameters to the
  * native #gnutls_x509_privkey_t format.  The output will be stored in
@@ -911,8 +913,8 @@ gnutls_x509_privkey_export_rsa_raw (gnutls_x509_privkey_t key,
  * @p: will hold the first prime (p)
  * @q: will hold the second prime (q)
  * @u: will hold the coefficient
- * @e1: will hold the exponent 1
- * @e2: will hold the exponent 2
+ * @e1: will hold e1 = d mod (p-1)
+ * @e2: will hold e2 = d mod (q-1)
  *
  * This function will export the RSA private key's parameters found
  * in the given structure. The new parameters will be allocated using