RECLAIM: cleanup, comments

3 files changed, 106 insertions, 70 deletions

diff --git a/src/include/gnunet_reclaim_attribute_lib.h b/src/include/gnunet_reclaim_attribute_lib.h
index db009da3f..e96937ea8 100644
--- a/src/include/gnunet_reclaim_attribute_lib.h
+++ b/src/include/gnunet_reclaim_attribute_lib.h
@@ -24,16 +24,15 @@
  * @file
  * Identity attribute definitions
  *
- * @defgroup identity-provider  Identity Provider service
+ * @defgroup reclaim-attribute reclaim attributes
  * @{
  */
 #ifndef GNUNET_RECLAIM_ATTRIBUTE_LIB_H
 #define GNUNET_RECLAIM_ATTRIBUTE_LIB_H
 
 #ifdef __cplusplus
-extern "C"
-{
-#if 0                           /* keep Emacsens' auto-indent happy */
+extern "C" {
+#if 0 /* keep Emacsens' auto-indent happy */
 }
 #endif
 #endif
@@ -52,7 +51,6 @@ extern "C"
 #define GNUNET_RECLAIM_ATTRIBUTE_TYPE_STRING 1
 
 
-
 /**
  * An attribute.
  */
@@ -76,7 +74,7 @@ struct GNUNET_RECLAIM_ATTRIBUTE_Claim
    * The name of the attribute. Note "name" must never be individually
    * free'd
    */
-  const char* name;
+  const char *name;
 
   /**
    * Number of bytes in @e data.
@@ -89,9 +87,12 @@ struct GNUNET_RECLAIM_ATTRIBUTE_Claim
    * existing data area.
    */
   const void *data;
-
 };
 
+
+/**
+ * A list of GNUNET_RECLAIM_ATTRIBUTE_Claim structures.
+ */
 struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList
 {
   /**
@@ -105,6 +106,7 @@ struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList
   struct GNUNET_RECLAIM_ATTRIBUTE_ClaimListEntry *list_tail;
 };
 
+
 struct GNUNET_RECLAIM_ATTRIBUTE_ClaimListEntry
 {
   /**
@@ -123,6 +125,7 @@ struct GNUNET_RECLAIM_ATTRIBUTE_ClaimListEntry
   struct GNUNET_RECLAIM_ATTRIBUTE_Claim *claim;
 };
 
+
 /**
  * Create a new attribute claim.
  *
@@ -133,9 +136,9 @@ struct GNUNET_RECLAIM_ATTRIBUTE_ClaimListEntry
  * @return the new attribute
  */
 struct GNUNET_RECLAIM_ATTRIBUTE_Claim *
-GNUNET_RECLAIM_ATTRIBUTE_claim_new (const char* attr_name,
+GNUNET_RECLAIM_ATTRIBUTE_claim_new (const char *attr_name,
                                     uint32_t type,
-                                    const void* data,
+                                    const void *data,
                                     size_t data_size);
 
 
@@ -143,57 +146,73 @@ GNUNET_RECLAIM_ATTRIBUTE_claim_new (const char* attr_name,
  * Get required size for serialization buffer
  *
  * @param attrs the attribute list to serialize
- *
  * @return the required buffer size
  */
 size_t
-GNUNET_RECLAIM_ATTRIBUTE_list_serialize_get_size (const struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs);
+GNUNET_RECLAIM_ATTRIBUTE_list_serialize_get_size (
+  const struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs);
+
 
+/**
+ * Destroy claim list
+ *
+ * @param attrs list to destroy
+ */
 void
-GNUNET_RECLAIM_ATTRIBUTE_list_destroy (struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs);
+GNUNET_RECLAIM_ATTRIBUTE_list_destroy (
+  struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs);
+
 
+/**
+ * Add a new attribute to a claim list
+ *
+ * @param attr_name the name of the new attribute claim
+ * @param type the type of the claim
+ * @param data claim payload
+ * @param data_size claim payload size
+ */
 void
-GNUNET_RECLAIM_ATTRIBUTE_list_add (struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs,
-                                   const char* attr_name,
-                                   uint32_t type,
-                                   const void* data,
-                                   size_t data_size);
+GNUNET_RECLAIM_ATTRIBUTE_list_add (
+  struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs,
+  const char *attr_name,
+  uint32_t type,
+  const void *data,
+  size_t data_size);
+
 
 /**
  * Serialize an attribute list
  *
  * @param attrs the attribute list to serialize
  * @param result the serialized attribute
- *
  * @return length of serialized data
  */
 size_t
-GNUNET_RECLAIM_ATTRIBUTE_list_serialize (const struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs,
-                                         char *result);
+GNUNET_RECLAIM_ATTRIBUTE_list_serialize (
+  const struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs,
+  char *result);
+
 
 /**
  * Deserialize an attribute list
  *
  * @param data the serialized attribute list
  * @param data_size the length of the serialized data
- *
  * @return a GNUNET_IDENTITY_PROVIDER_AttributeList, must be free'd by caller
  */
 struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *
-GNUNET_RECLAIM_ATTRIBUTE_list_deserialize (const char* data,
-                                           size_t data_size);
+GNUNET_RECLAIM_ATTRIBUTE_list_deserialize (const char *data, size_t data_size);
 
 
 /**
  * Get required size for serialization buffer
  *
  * @param attr the attribute to serialize
- *
  * @return the required buffer size
  */
 size_t
-GNUNET_RECLAIM_ATTRIBUTE_serialize_get_size (const struct GNUNET_RECLAIM_ATTRIBUTE_Claim *attr);
-
+GNUNET_RECLAIM_ATTRIBUTE_serialize_get_size (
+  const struct GNUNET_RECLAIM_ATTRIBUTE_Claim *attr);
 
 
 /**
@@ -201,12 +220,13 @@ GNUNET_RECLAIM_ATTRIBUTE_serialize_get_size (const struct GNUNET_RECLAIM_ATTRIBU
  *
  * @param attr the attribute to serialize
  * @param result the serialized attribute
- *
  * @return length of serialized data
  */
 size_t
-GNUNET_RECLAIM_ATTRIBUTE_serialize (const struct GNUNET_RECLAIM_ATTRIBUTE_Claim *attr,
-                                    char *result);
+GNUNET_RECLAIM_ATTRIBUTE_serialize (
+  const struct GNUNET_RECLAIM_ATTRIBUTE_Claim *attr,
+  char *result);
+
 
 /**
  * Deserialize an attribute
@@ -217,11 +237,18 @@ GNUNET_RECLAIM_ATTRIBUTE_serialize (const struct GNUNET_RECLAIM_ATTRIBUTE_Claim
  * @return a GNUNET_IDENTITY_PROVIDER_Attribute, must be free'd by caller
  */
 struct GNUNET_RECLAIM_ATTRIBUTE_Claim *
-GNUNET_RECLAIM_ATTRIBUTE_deserialize (const char* data,
-                                      size_t data_size);
+GNUNET_RECLAIM_ATTRIBUTE_deserialize (const char *data, size_t data_size);
+
+
+/**
+ * Make a (deep) copy of a claim list
+ * @param attrs claim list to copy
+ * @return copied claim list
+ */
+struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *
+GNUNET_RECLAIM_ATTRIBUTE_list_dup (
+  const struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs);
 
-struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList*
-GNUNET_RECLAIM_ATTRIBUTE_list_dup (const struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs);
 
 /**
  * Convert a type name to the corresponding number
@@ -248,6 +275,7 @@ GNUNET_RECLAIM_ATTRIBUTE_string_to_value (uint32_t type,
                                           void **data,
                                           size_t *data_size);
 
+
 /**
  * Convert the 'claim' of an attribute to a string
  *
@@ -258,20 +286,21 @@ GNUNET_RECLAIM_ATTRIBUTE_string_to_value (uint32_t type,
  */
 char *
 GNUNET_RECLAIM_ATTRIBUTE_value_to_string (uint32_t type,
-                                          const void* data,
+                                          const void *data,
                                           size_t data_size);
 
+
 /**
  * Convert a type number to the corresponding type string
  *
  * @param type number of a type
  * @return corresponding typestring, NULL on error
  */
-const char*
+const char *
 GNUNET_RECLAIM_ATTRIBUTE_number_to_typename (uint32_t type);
 
 
-#if 0                           /* keep Emacsens' auto-indent happy */
+#if 0 /* keep Emacsens' auto-indent happy */
 {
 #endif
 #ifdef __cplusplus
@@ -282,6 +311,6 @@ GNUNET_RECLAIM_ATTRIBUTE_number_to_typename (uint32_t type);
 /* ifndef GNUNET_RECLAIM_ATTRIBUTE_LIB_H */
 #endif
 
-/** @} */ /* end of group identity */
+/** @} */ /* end of group reclaim-attribute */
 
 /* end of gnunet_reclaim_attribute_lib.h */
diff --git a/src/include/gnunet_reclaim_attribute_plugin.h b/src/include/gnunet_reclaim_attribute_plugin.h
index 0dfd69b82..c05c80b07 100644
--- a/src/include/gnunet_reclaim_attribute_plugin.h
+++ b/src/include/gnunet_reclaim_attribute_plugin.h
@@ -11,7 +11,7 @@
      WITHOUT ANY WARRANTY; without even the implied warranty of
      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
      Affero General Public License for more details.
-    
+
      You should have received a copy of the GNU Affero General Public License
      along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
@@ -22,10 +22,9 @@
  * @author Martin Schanzenbach
  *
  * @file
- * Plugin API for the idp database backend
+ * Plugin API for reclaim attribute types
  *
- * @defgroup identity-provider-plugin  IdP service plugin API
- * Plugin API for the idp database backend
+ * @defgroup reclaim-attribute-plugin  reclaim plugin API for attributes/claims
  * @{
  */
 #ifndef GNUNET_RECLAIM_ATTRIBUTE_PLUGIN_H
@@ -35,9 +34,8 @@
 #include "gnunet_reclaim_attribute_lib.h"
 
 #ifdef __cplusplus
-extern "C"
-{
-#if 0                           /* keep Emacsens' auto-indent happy */
+extern "C" {
+#if 0 /* keep Emacsens' auto-indent happy */
 }
 #endif
 #endif
@@ -53,10 +51,11 @@ extern "C"
  * @param data_size number of bytes in @a data
  * @return NULL on error, otherwise human-readable representation of the value
  */
-typedef char * (*GNUNET_RECLAIM_ATTRIBUTE_ValueToStringFunction) (void *cls,
-                                                          uint32_t type,
-                                                          const void *data,
-                                                          size_t data_size);
+typedef char *(*GNUNET_RECLAIM_ATTRIBUTE_ValueToStringFunction) (
+  void *cls,
+  uint32_t type,
+  const void *data,
+  size_t data_size);
 
 
 /**
@@ -71,11 +70,12 @@ typedef char * (*GNUNET_RECLAIM_ATTRIBUTE_ValueToStringFunction) (void *cls,
  * @param data_size set to number of bytes in @a data
  * @return #GNUNET_OK on success
  */
-typedef int (*GNUNET_RECLAIM_ATTRIBUTE_StringToValueFunction) (void *cls,
-                                                       uint32_t type,
-                                                       const char *s,
-                                                       void **data,
-                                                       size_t *data_size);
+typedef int (*GNUNET_RECLAIM_ATTRIBUTE_StringToValueFunction) (
+  void *cls,
+  uint32_t type,
+  const char *s,
+  void **data,
+  size_t *data_size);
 
 
 /**
@@ -86,8 +86,9 @@ typedef int (*GNUNET_RECLAIM_ATTRIBUTE_StringToValueFunction) (void *cls,
  * @param typename name to convert
  * @return corresponding number, UINT32_MAX on error
  */
-typedef uint32_t (*GNUNET_RECLAIM_ATTRIBUTE_TypenameToNumberFunction) (void *cls,
-                                                               const char *typename);
+typedef uint32_t (*GNUNET_RECLAIM_ATTRIBUTE_TypenameToNumberFunction) (
+  void *cls,
+  const char *typename);
 
 
 /**
@@ -98,8 +99,9 @@ typedef uint32_t (*GNUNET_RECLAIM_ATTRIBUTE_TypenameToNumberFunction) (void *cls
  * @param type number of a type to convert
  * @return corresponding typestring, NULL on error
  */
-typedef const char * (*GNUNET_RECLAIM_ATTRIBUTE_NumberToTypenameFunction) (void *cls,
-                                                                   uint32_t type);
+typedef const char *(*GNUNET_RECLAIM_ATTRIBUTE_NumberToTypenameFunction) (
+  void *cls,
+  uint32_t type);
 
 
 /**
@@ -133,11 +135,10 @@ struct GNUNET_RECLAIM_ATTRIBUTE_PluginFunctions
    * Number to typename.
    */
   GNUNET_RECLAIM_ATTRIBUTE_NumberToTypenameFunction number_to_typename;
-
 };
 
 
-#if 0                           /* keep Emacsens' auto-indent happy */
+#if 0 /* keep Emacsens' auto-indent happy */
 {
 #endif
 #ifdef __cplusplus
@@ -146,4 +147,4 @@ struct GNUNET_RECLAIM_ATTRIBUTE_PluginFunctions
 
 #endif
 
-/** @} */  /* end of group */
+/** @} */ /* end of group */
diff --git a/src/include/gnunet_reclaim_service.h b/src/include/gnunet_reclaim_service.h
index fc3d0f920..8d7babd7c 100644
--- a/src/include/gnunet_reclaim_service.h
+++ b/src/include/gnunet_reclaim_service.h
@@ -22,9 +22,10 @@
  * @author Martin Schanzenbach
  *
  * @file
- * Identity provider service; implements identity provider for GNUnet
+ * reclaim service; implements identity and personal data sharing
+ * for GNUnet
  *
- * @defgroup reclaim  Identity Provider service
+ * @defgroup reclaim service
  * @{
  */
 #ifndef GNUNET_RECLAIM_SERVICE_H
@@ -43,7 +44,7 @@ extern "C" {
 /**
  * Version number of the re:claimID API.
  */
-#define GNUNET_RECLAIM_VERSION 0x00000000
+#define GNUNET_RECLAIM_VERSION 0x00000001
 
 /**
  * Opaque handle to access the service.
@@ -58,10 +59,10 @@ struct GNUNET_RECLAIM_Operation;
 
 
 /**
- * The an authorization ticket. This ticket is meant to be transferred
- * out of band the a relying party.
+ * The authorization ticket. This ticket is meant to be transferred
+ * out of band to a relying party.
  * The contents of a ticket must be protected and should be treated as a
- * SHARED SECRET between user and relying party.
+ * shared secret between user and relying party.
  */
 struct GNUNET_RECLAIM_Ticket
 {
@@ -84,8 +85,8 @@ struct GNUNET_RECLAIM_Ticket
 
 /**
  * Method called when a token has been issued.
- * On success returns a ticket that can be given to the relying party to retrive
- * the token
+ * On success returns a ticket that can be given to a relying party
+ * in order for it retrive identity attributes
  *
  * @param cls closure
  * @param ticket the ticket
@@ -133,7 +134,7 @@ GNUNET_RECLAIM_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
  * Store an attribute.  If the attribute is already present,
  * it is replaced with the new attribute.
  *
- * @param h handle to the re:claimID service
+ * @param h handle to the reclaim service
  * @param pkey Private key of the identity to add an attribute to
  * @param attr The attribute
  * @param exp_interval The relative expiration interval for the attribute
@@ -246,6 +247,7 @@ GNUNET_RECLAIM_ticket_issue (
     const struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs,
     GNUNET_RECLAIM_TicketCallback cb, void *cb_cls);
 
+
 /**
  * Revoked an issued ticket. The relying party will be unable to retrieve
  * attributes. Other issued tickets remain unaffected.
@@ -286,6 +288,7 @@ GNUNET_RECLAIM_ticket_consume (
     const struct GNUNET_RECLAIM_Ticket *ticket,
     GNUNET_RECLAIM_AttributeResult cb, void *cb_cls);
 
+
 /**
  * Lists all tickets that have been issued to remote
  * identites (relying parties)
@@ -321,6 +324,7 @@ GNUNET_RECLAIM_ticket_iteration_start (
 void
 GNUNET_RECLAIM_ticket_iteration_next (struct GNUNET_RECLAIM_TicketIterator *it);
 
+
 /**
  * Stops iteration and releases the handle for further calls.  Must
  * be called on any iteration that has not yet completed prior to calling
@@ -331,6 +335,7 @@ GNUNET_RECLAIM_ticket_iteration_next (struct GNUNET_RECLAIM_TicketIterator *it);
 void
 GNUNET_RECLAIM_ticket_iteration_stop (struct GNUNET_RECLAIM_TicketIterator *it);
 
+
 /**
  * Disconnect from identity provider service.
  *
@@ -351,6 +356,7 @@ GNUNET_RECLAIM_disconnect (struct GNUNET_RECLAIM_Handle *h);
 void
 GNUNET_RECLAIM_cancel (struct GNUNET_RECLAIM_Operation *op);
 
+
 #if 0 /* keep Emacsens' auto-indent happy */
 {
 #endif
@@ -362,6 +368,6 @@ GNUNET_RECLAIM_cancel (struct GNUNET_RECLAIM_Operation *op);
 /* ifndef GNUNET_RECLAIM_SERVICE_H */
 #endif
 
-/** @} */ /* end of group identity */
+/** @} */ /* end of group reclaim */
 
 /* end of gnunet_reclaim_service.h */