-cleanup doc; fixes

6 files changed, 84 insertions, 50 deletions

diff --git a/src/include/gnunet_abe_lib.h b/src/include/gnunet_abe_lib.h
index 77b0f9e99..f73ea2431 100644
--- a/src/include/gnunet_abe_lib.h
+++ b/src/include/gnunet_abe_lib.h
@@ -19,8 +19,8 @@
 */
 
 /**
- * @file include/gnunet_crypto_lib.h
- * @brief cryptographic primitives for GNUnet
+ * @file include/gnunet_abe_lib.h
+ * @brief Attribute-Based Encryption primitives for GNUnet
  *
  * @author Martin Schanzenbach
  *
@@ -57,10 +57,18 @@ struct GNUNET_CRYPTO_AbeKey;
  * @ingroup abe
  * Create a new CP-ABE master key. Caller must free return value.
  *
- * @return fresh private key; free using #GNUNET_free
+ * @return fresh private key; free using #GNUNET_ABE_cpabe_delete_master_key
  */
 struct GNUNET_ABE_AbeMasterKey *
 GNUNET_ABE_cpabe_create_master_key (void);
+
+/**
+ * @ingroup abe
+ * Delete a CP-ABE master key.
+ *
+ * @param key the master key
+ * @return fresh private key; free using #GNUNET_free
+ */
 void
 GNUNET_ABE_cpabe_delete_master_key (struct GNUNET_ABE_AbeMasterKey *key);
 
@@ -68,11 +76,22 @@ GNUNET_ABE_cpabe_delete_master_key (struct GNUNET_ABE_AbeMasterKey *key);
  * @ingroup abe
  * Create a new CP-ABE key. Caller must free return value.
  *
- * @return fresh private key; free using #GNUNET_free
+ * @param key the master key
+ * @param attrs the attributes to append to the key
+ * @return fresh private key; free using #GNUNET_ABE_cpabe_delete_key
  */
 struct GNUNET_ABE_AbeKey *
-GNUNET_ABE_cpabe_create_key (struct GNUNET_ABE_AbeMasterKey *msk,
+GNUNET_ABE_cpabe_create_key (struct GNUNET_ABE_AbeMasterKey *key,
                                 char **attrs);
+
+/**
+ * @ingroup abe
+ * Delete a CP-ABE key.
+ *
+ * @param key the key to delete
+ * @param delete_pub GNUNE_YES if the public key should also be freed (bug in gabe)
+ * @return fresh private key; free using #GNUNET_free
+ */
 void
 GNUNET_ABE_cpabe_delete_key (struct GNUNET_ABE_AbeKey *key,
                                 int delete_pub);
@@ -84,9 +103,9 @@ GNUNET_ABE_cpabe_delete_key (struct GNUNET_ABE_AbeKey *key,
  *
  * @param block the block to encrypt
  * @param size the size of the @a block
- * @param sessionkey the key used to encrypt
- * @param iv the initialization vector to use, use INITVALUE
- *        for streams.
+ * @param policy the ABE policy
+ * @param key the key used to encrypt
+ * @param result the result buffer. Will be allocated. Free using #GNUNET_free
  * @return the size of the encrypted block, -1 for errors
  */
 ssize_t
@@ -98,13 +117,12 @@ GNUNET_ABE_cpabe_encrypt (const void *block,
 
 /**
  * @ingroup abe
- * Encrypt a block using  sessionkey.
+ * Decrypt a block using the ABE key.
  *
  * @param block the block to encrypt
  * @param size the size of the @a block
- * @param sessionkey the key used to encrypt
- * @param iv the initialization vector to use, use INITVALUE
- *        for streams.
+ * @param key the key used to decrypt
+ * @param result the result buffer. Will be allocated. Free using #GNUNET_free
  * @return the size of the encrypted block, -1 for errors
  */
 ssize_t
@@ -113,18 +131,50 @@ GNUNET_ABE_cpabe_decrypt (const void *block,
                              const struct GNUNET_ABE_AbeKey *key,
                              void **result);
 
+/**
+ * @ingroup abe
+ * Serialize an ABE key.
+ *
+ * @param key the key to serialize
+ * @param result the result buffer. Will be allocated. Free using #GNUNET_free
+ * @return the size of the encrypted block, -1 for errors
+ */
 ssize_t
 GNUNET_ABE_cpabe_serialize_key (const struct GNUNET_ABE_AbeKey *key,
                                    void **result);
 
+/**
+ * @ingroup abe
+ * Deserialize a serialized ABE key.
+ *
+ * @param data the data to deserialize
+ * @param len the length of the data.
+ * @return the ABE key. NULL of unsuccessful
+ */
 struct GNUNET_ABE_AbeKey*
 GNUNET_ABE_cpabe_deserialize_key (const void *data,
                                      size_t len);
 
+/**
+ * @ingroup abe
+ * Serialize an ABE master key.
+ *
+ * @param key the key to serialize
+ * @param result the result buffer. Will be allocated. Free using #GNUNET_free
+ * @return the size of the encrypted block, -1 for errors
+ */
 ssize_t
 GNUNET_ABE_cpabe_serialize_master_key (const struct GNUNET_ABE_AbeMasterKey *key,
                                           void **result);
 
+/**
+ * @ingroup abe
+ * Deserialize an ABE master key.
+ *
+ * @param data the data to deserialize
+ * @param len the length of the data.
+ * @return the ABE key. NULL of unsuccessful
+ */
 struct GNUNET_ABE_AbeMasterKey*
 GNUNET_ABE_cpabe_deserialize_master_key (const void *data,
                                             size_t len);
diff --git a/src/include/gnunet_credential_service.h b/src/include/gnunet_credential_service.h
index 67c2f2b4c..7d6f9e973 100644
--- a/src/include/gnunet_credential_service.h
+++ b/src/include/gnunet_credential_service.h
@@ -20,7 +20,6 @@
 
 /**
  * @author Martin Schanzenbach
- * @author Adnan Husain
  *
  * @file
  * API to the Credential service
@@ -274,7 +273,8 @@ typedef void (*GNUNET_CREDENTIAL_RemoveDelegateResultProcessor) (void *cls,
  * @param issuer_key the issuer public key
  * @param issuer_attribute the issuer attribute
  * @param subject_key the subject public key
- * @param subject_attribute the attribute claimed by the subject
+ * @param credential_count number of credentials
+ * @param credentials the subject credentials
  * @param proc function to call on result
  * @param proc_cls closure for processor
  * @return handle to the queued request
@@ -305,6 +305,8 @@ GNUNET_CREDENTIAL_collect (struct GNUNET_CREDENTIAL_Handle *handle,
  * @param attribute the name of the attribute to delegate
  * @param subject the subject of the delegation
  * @param delegated_attribute the name of the attribute that is delegated to
+ * @param proc the result callback
+ * @param proc_cls the result closure context
  * @return handle to the queued request
  */
 struct GNUNET_CREDENTIAL_Request *
@@ -322,6 +324,8 @@ GNUNET_CREDENTIAL_add_delegation (struct GNUNET_CREDENTIAL_Handle *handle,
  * @param handle handle to the Credential service
  * @param issuer the ego that was used to delegate the attribute
  * @param attribute the name of the attribute that is delegated
+ * @param proc the callback
+ * @param proc_cls callback closure
  * @return handle to the queued request
  */
 struct GNUNET_CREDENTIAL_Request *
@@ -336,7 +340,6 @@ GNUNET_CREDENTIAL_remove_delegation (struct GNUNET_CREDENTIAL_Handle *handle,
 /**
  * Issue an attribute to a subject
  *
- * @param handle handle to the Credential service
  * @param issuer the ego that should be used to issue the attribute
  * @param subject the subject of the attribute
  * @param attribute the name of the attribute
@@ -344,32 +347,12 @@ GNUNET_CREDENTIAL_remove_delegation (struct GNUNET_CREDENTIAL_Handle *handle,
  * @return handle to the queued request
  */
 struct GNUNET_CREDENTIAL_Credential*
-GNUNET_CREDENTIAL_credential_issue (
-                                    const struct GNUNET_CRYPTO_EcdsaPrivateKey *issuer,
+GNUNET_CREDENTIAL_credential_issue (const struct GNUNET_CRYPTO_EcdsaPrivateKey *issuer,
                                     struct GNUNET_CRYPTO_EcdsaPublicKey *subject,
                                     const char *attribute,
                                     struct GNUNET_TIME_Absolute *expiration);
 
 
-/**
- * Remove a credential
- *
- * @param handle handle to the Credential service
- * @param issuer the identity that issued the credential
- * @param subject the subject of the credential
- * @param credential the name of the credential
- * @return handle to the queued request
- */
-/**
-  struct GNUNET_CREDENTIAL_IssueRequest *
-  GNUNET_CREDENTIAL_remove (struct GNUNET_CREDENTIAL_Handle *handle,
-  struct GNUNET_IDENTITY_Ego *issuer,
-  struct GNUNET_IDENTITY_Ego *subject,
-  const char *credential,
-  GNUNET_CREDENTIAL_IssueResultProcessor proc,
-  void *proc_cls);
-  */
-
 
 /**
  * Cancel pending lookup request
@@ -377,7 +360,7 @@ GNUNET_CREDENTIAL_credential_issue (
  * @param lr the lookup request to cancel
  */
 void
-GNUNET_CREDENTIAL_request_cancel (struct GNUNET_CREDENTIAL_Request *vr);
+GNUNET_CREDENTIAL_request_cancel (struct GNUNET_CREDENTIAL_Request *lr);
 
 
 #if 0                           /* keep Emacsens' auto-indent happy */
diff --git a/src/include/gnunet_identity_attribute_lib.h b/src/include/gnunet_identity_attribute_lib.h
index a6c9e1f1c..316b0bf95 100644
--- a/src/include/gnunet_identity_attribute_lib.h
+++ b/src/include/gnunet_identity_attribute_lib.h
@@ -122,7 +122,7 @@ struct GNUNET_IDENTITY_ATTRIBUTE_ClaimListEntry
 /**
  * Create a new attribute claim.
  *
- * @param name the attribute name
+ * @param attr_name the attribute name
  * @param type the attribute type
  * @param data the attribute value
  * @param data_size the attribute value size
diff --git a/src/include/gnunet_identity_provider_service.h b/src/include/gnunet_identity_provider_service.h
index 6bc05d0f4..be935e898 100644
--- a/src/include/gnunet_identity_provider_service.h
+++ b/src/include/gnunet_identity_provider_service.h
@@ -131,6 +131,7 @@ GNUNET_IDENTITY_PROVIDER_attribute_store (struct GNUNET_IDENTITY_PROVIDER_Handle
  * Process an attribute that was stored in the idp.
  *
  * @param cls closure
+ * @param identity the identity
  * @param attr the attribute
  */
 typedef void
@@ -211,19 +212,19 @@ typedef void
 
 /**
  * Issues a ticket to another identity. The identity may use
- * @GNUNET_IDENTITY_PROVIDER_authorization_ticket_consume to consume the ticket
+ * GNUNET_IDENTITY_PROVIDER_ticket_consume to consume the ticket
  * and retrieve the attributes specified in the AttributeList.
  *
- * @param id the identity provider to use
+ * @param h the identity provider to use
  * @param iss the issuing identity
  * @param rp the subject of the ticket (the relying party)
- * @param attr the attributes that the relying party is given access to
+ * @param attrs the attributes that the relying party is given access to
  * @param cb the callback
  * @param cb_cls the callback closure
  * @return handle to abort the operation
  */
 struct GNUNET_IDENTITY_PROVIDER_Operation *
-GNUNET_IDENTITY_PROVIDER_ticket_issue (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
+GNUNET_IDENTITY_PROVIDER_ticket_issue (struct GNUNET_IDENTITY_PROVIDER_Handle *h,
                                        const struct GNUNET_CRYPTO_EcdsaPrivateKey *iss,
                                        const struct GNUNET_CRYPTO_EcdsaPublicKey *rp,
                                        const struct GNUNET_IDENTITY_ATTRIBUTE_ClaimList *attrs,
@@ -234,7 +235,7 @@ GNUNET_IDENTITY_PROVIDER_ticket_issue (struct GNUNET_IDENTITY_PROVIDER_Handle *i
  * Revoked an issued ticket. The relying party will be unable to retrieve
  * updated attributes.
  *
- * @param id the identity provider to use
+ * @param h the identity provider to use
  * @param identity the issuing identity
  * @param ticket the ticket to revoke
  * @param cb the callback
@@ -242,7 +243,7 @@ GNUNET_IDENTITY_PROVIDER_ticket_issue (struct GNUNET_IDENTITY_PROVIDER_Handle *i
  * @return handle to abort the operation
  */
 struct GNUNET_IDENTITY_PROVIDER_Operation *
-GNUNET_IDENTITY_PROVIDER_ticket_revoke (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
+GNUNET_IDENTITY_PROVIDER_ticket_revoke (struct GNUNET_IDENTITY_PROVIDER_Handle *h,
                                         const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity,
                                         const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket,
                                         GNUNET_IDENTITY_PROVIDER_ContinuationWithStatus cb,
@@ -254,7 +255,7 @@ GNUNET_IDENTITY_PROVIDER_ticket_revoke (struct GNUNET_IDENTITY_PROVIDER_Handle *
  * Consumes an issued ticket. The ticket is persisted
  * and used to retrieve identity information from the issuer
  *
- * @param id the identity provider to use
+ * @param h the identity provider to use
  * @param identity the identity that is the subject of the issued ticket (the audience)
  * @param ticket the issued ticket to consume
  * @param cb the callback to call
@@ -262,7 +263,7 @@ GNUNET_IDENTITY_PROVIDER_ticket_revoke (struct GNUNET_IDENTITY_PROVIDER_Handle *
  * @return handle to abort the operation
  */
 struct GNUNET_IDENTITY_PROVIDER_Operation *
-GNUNET_IDENTITY_PROVIDER_ticket_consume (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
+GNUNET_IDENTITY_PROVIDER_ticket_consume (struct GNUNET_IDENTITY_PROVIDER_Handle *h,
                                          const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity,
                                          const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket,
                                          GNUNET_IDENTITY_PROVIDER_AttributeResult cb,
@@ -299,7 +300,7 @@ GNUNET_IDENTITY_PROVIDER_ticket_iteration_start (struct GNUNET_IDENTITY_PROVIDER
  * Lists all tickets that have been issued to remote
  * identites (relying parties)
  *
- * @param id the identity provider to use
+ * @param h the identity provider to use
  * @param identity the issuing identity
  * @param error_cb function to call on error (i.e. disconnect),
  *        the handle is afterwards invalid
diff --git a/src/include/gnunet_rest_lib.h b/src/include/gnunet_rest_lib.h
index a4dbb0696..e571eead3 100644
--- a/src/include/gnunet_rest_lib.h
+++ b/src/include/gnunet_rest_lib.h
@@ -89,7 +89,7 @@ typedef void (*GNUNET_REST_ResultProcessor) (void *cls,
  *
  * @param url URL to check
  * @param namespace namespace to check against
- * @retun GNUNET_YES if namespace matches
+ * @return GNUNET_YES if namespace matches
  */
 int
 GNUNET_REST_namespace_match (const char *url, const char *namespace);
@@ -98,7 +98,7 @@ GNUNET_REST_namespace_match (const char *url, const char *namespace);
  * Create REST MHD response
  *
  * @param data result
- * @retun MHD response
+ * @return MHD response
  */
  struct MHD_Response*
 GNUNET_REST_create_response (const char *data);
diff --git a/src/include/gnunet_rest_plugin.h b/src/include/gnunet_rest_plugin.h
index ecd5f66f1..424dbb1fc 100644
--- a/src/include/gnunet_rest_plugin.h
+++ b/src/include/gnunet_rest_plugin.h
@@ -57,7 +57,7 @@ struct GNUNET_REST_Plugin
 
   /**
    * Plugin name. Used as the namespace for the API.
-   * e.g. http://hostname:port/<name>
+   * e.g. http://hostname:port/name
    */
   char *name;