-documentation on new api

2 files changed, 71 insertions, 2 deletions

diff --git a/src/include/gnunet_gnsrecord_lib.h b/src/include/gnunet_gnsrecord_lib.h
index 559208689..22e7c0e25 100644
--- a/src/include/gnunet_gnsrecord_lib.h
+++ b/src/include/gnunet_gnsrecord_lib.h
@@ -659,19 +659,35 @@ size_t
 GNUNET_GNSRECORD_block_get_size (const struct GNUNET_GNSRECORD_Block *block);
 
 /**
- * Returns the expiration of a block
+ * Returns the expiration of a block.
+ *
+ * @param block the block.
+ * @return the block expiration.
  */
 struct GNUNET_TIME_Absolute
 GNUNET_GNSRECORD_block_get_expiration (const struct GNUNET_GNSRECORD_Block *block);
 
 
 /**
- * Builds the query from a block
+ * Builds the query hash from a block.
+ *
+ * @param block the block.
+ * @param query where to write the query hash.
+ * @return GNUNET_SYSERR on error.
  */
 enum GNUNET_GenericReturnValue
 GNUNET_GNSRECORD_query_from_block (const struct GNUNET_GNSRECORD_Block *block,
                                    struct GNUNET_HashCode *query);
 
+
+/**
+ * Build a #GNUNET_GNSRECORD_PublicKey from a
+ * zone delegation resource record set.
+ *
+ * @param the resource record set. MUST be a delegation record.
+ * @param key where to write the identtiy key.
+ * @return GNUNET_SYSERR on error or if the zone is not a delegation zone.
+ */
 enum GNUNET_GenericReturnValue
 GNUNET_GNSRECORD_record_to_identity_key (const struct GNUNET_GNSRECORD_Data *rd,
                                          struct GNUNET_IDENTITY_PublicKey *key);
diff --git a/src/include/gnunet_identity_service.h b/src/include/gnunet_identity_service.h
index c72e6d146..3352d9bc0 100644
--- a/src/include/gnunet_identity_service.h
+++ b/src/include/gnunet_identity_service.h
@@ -363,27 +363,80 @@ GNUNET_IDENTITY_delete (struct GNUNET_IDENTITY_Handle *id,
 void
 GNUNET_IDENTITY_cancel (struct GNUNET_IDENTITY_Operation *op);
 
+
+/**
+ * Get the compacted length of a #GNUNET_IDENTITY_PublicKey.
+ * Compacted means that it returns the minimum number of bytes this
+ * key is long, as opposed to the union structure inside
+ * #GNUNET_IDENTITY_PublicKey.
+ * Useful for compact serializations.
+ *
+ * @param key the key.
+ * @return -1 on error, else the compacted length of the key.
+ */
 ssize_t
 GNUNET_IDENTITY_key_get_length (const struct GNUNET_IDENTITY_PublicKey *key);
 
+
+/**
+ * Creates a (Base32) string representation of the public key.
+ * The resulting string encodes a compacted representation of the key.
+ * See also #GNUNET_IDENTITY_key_get_length.
+ *
+ * @param key the key.
+ * @return the string representation of the key, or NULL on error.
+ */
 char *
 GNUNET_IDENTITY_public_key_to_string (const struct
                                       GNUNET_IDENTITY_PublicKey *key);
 
 
+/**
+ * Creates a (Base32) string representation of the private key.
+ * The resulting string encodes a compacted representation of the key.
+ * See also #GNUNET_IDENTITY_key_get_length.
+ *
+ * @param key the key.
+ * @return the string representation of the key, or NULL on error.
+ */
 char *
 GNUNET_IDENTITY_private_key_to_string (const struct
                                        GNUNET_IDENTITY_PrivateKey *key);
 
 
+/**
+ * Parses a (Base32) string representation of the public key.
+ * See also #GNUNET_IDENTITY_public_key_to_string.
+ *
+ * @param str the encoded key.
+ * @param key where to write the key.
+ * @return GNUNET_SYSERR on error.
+ */
 enum GNUNET_GenericReturnValue
 GNUNET_IDENTITY_public_key_from_string (const char*str,
                                         struct GNUNET_IDENTITY_PublicKey *key);
 
+
+/**
+ * Parses a (Base32) string representation of the private key.
+ * See also #GNUNET_IDENTITY_private_key_to_string.
+ *
+ * @param str the encoded key.
+ * @param key where to write the key.
+ * @return GNUNET_SYSERR on error.
+ */
 enum GNUNET_GenericReturnValue
 GNUNET_IDENTITY_private_key_from_string (const char*str,
                                          struct GNUNET_IDENTITY_PrivateKey *key);
 
+
+/**
+ * Retrieves the public key representation of a private key.
+ *
+ * @param privkey the private key.
+ * @param key the public key result.
+ * @return GNUNET_SYSERR on error.
+ */
 enum GNUNET_GenericReturnValue
 GNUNET_IDENTITY_key_get_public (const struct GNUNET_IDENTITY_PrivateKey *privkey,
                                 struct GNUNET_IDENTITY_PublicKey *key);