fixing minor memory leak, improving documentation

2 files changed, 109 insertions, 64 deletions

diff --git a/src/mint/key_io.c b/src/mint/key_io.c
index 928d51db3..ad06da62d 100644
--- a/src/mint/key_io.c
+++ b/src/mint/key_io.c
@@ -13,7 +13,6 @@
   You should have received a copy of the GNU General Public License along with
   TALER; see the file COPYING.  If not, If not, see <http://www.gnu.org/licenses/>
 */
-
 /**
  * @file mint/key_io.c
  * @brief I/O operations for the Mint's private keys
@@ -23,36 +22,40 @@
  * @author Christian Grothoff
  *
  * TODO:
- * - document better
  * - revisit IO with respect to variable-size RSA keys!
  */
 #include "platform.h"
 #include "key_io.h"
 
+
 /**
- *
+ * Closure for the #signkeys_iterate_dir_iter().
  */
 struct SignkeysIterateContext
 {
 
   /**
-   *
+   * Function to call on each signing key.
    */
   TALER_MINT_SignkeyIterator it;
 
   /**
-   *
+   * Closure for @e it.
    */
   void *it_cls;
 };
 
 
 /**
+ * Function called on each file in the directory with
+ * our signing keys. Parses the file and calls the
+ * iterator from @a cls.
  *
- *
- * @param cls
- * @param filename
- * @return
+ * @param cls the `struct SignkeysIterateContext *`
+ * @param filename name of the file to parse
+ * @return #GNUNET_OK to continue,
+ *         #GNUNET_NO to stop iteration without error,
+ *         #GNUNET_SYSERR to stop iteration with error
  */
 static int
 signkeys_iterate_dir_iter (void *cls,
@@ -78,6 +81,18 @@ signkeys_iterate_dir_iter (void *cls,
 }
 
 
+/**
+ * Call @a it for each signing key found in the @a mint_base_dir.
+ *
+ * @param mint_base_dir base directory for the mint,
+ *                      the signing keys must be in the #DIR_SIGNKEYS
+ *                      subdirectory
+ * @param it function to call on each signing key
+ * @param it_cls closure for @a it
+ * @return number of files found (may not match
+ *         number of keys given to @a it as malformed
+ *         files are simply skipped), -1 on error
+ */
 int
 TALER_MINT_signkeys_iterate (const char *mint_base_dir,
                              TALER_MINT_SignkeyIterator it,
@@ -101,10 +116,10 @@ TALER_MINT_signkeys_iterate (const char *mint_base_dir,
 
 
 /**
- * Import a denomination key from the given file
+ * Import a denomination key from the given file.
  *
  * @param filename the file to import the key from
- * @param dki pointer to return the imported denomination key
+ * @param[OUT] dki set to the imported denomination key
  * @return #GNUNET_OK upon success; #GNUNET_SYSERR upon failure
  */
 int
@@ -203,34 +218,40 @@ TALER_MINT_write_denom_key (const char *filename,
 
 
 /**
- *
+ * Closure for #denomkeys_iterate_keydir_iter() and
+ * #denomkeys_iterate_topdir_iter().
  */
 struct DenomkeysIterateContext
 {
 
   /**
-   *
+   * Set to the name of the directory below the top-level directory
+   * during the call to #denomkeys_iterate_keydir_iter().
    */
   const char *alias;
 
   /**
-   *
+   * Function to call on each denomination key.
    */
   TALER_MINT_DenomkeyIterator it;
 
   /**
-   *
+   * Closure for @e it.
    */
   void *it_cls;
 };
 
 
 /**
+ * Decode the denomination key in the given file @a filename and call
+ * the callback in @a cls with the information.
  *
- *
- * @param cls
- * @param filename
- * @return
+ * @param cls the `struct DenomkeysIterateContext *`
+ * @param filename name of a file that should contain
+ *                 a denomination key
+ * @return #GNUNET_OK to continue to iterate
+ *         #GNUNET_NO to abort iteration with success
+ *         #GNUNET_SYSERR to abort iteration with failure
  */
 static int
 denomkeys_iterate_keydir_iter (void *cls,
@@ -255,11 +276,14 @@ denomkeys_iterate_keydir_iter (void *cls,
 
 
 /**
+ * Function called on each subdirectory in the #DIR_DENOMKEYS.  Will
+ * call the #denomkeys_iterate_keydir_iter() on each file in the
+ * subdirectory.
  *
- *
- * @param cls
- * @param filename
- * @return
+ * @param cls the `struct DenomkeysIterateContext *`
+ * @param filename name of the subdirectory to scan
+ * @return #GNUNET_OK on success,
+ *         #GNUNET_SYSERR if we need to abort
  */
 static int
 denomkeys_iterate_topdir_iter (void *cls,
@@ -268,8 +292,6 @@ denomkeys_iterate_topdir_iter (void *cls,
   struct DenomkeysIterateContext *dic = cls;
 
   dic->alias = GNUNET_STRINGS_get_short_name (filename);
-
-  // FIXME: differentiate between error case and normal iteration abortion
   if (0 > GNUNET_DISK_directory_scan (filename,
                                       &denomkeys_iterate_keydir_iter,
                                       dic))
@@ -278,6 +300,19 @@ denomkeys_iterate_topdir_iter (void *cls,
 }
 
 
+/**
+ * Call @a it for each denomination key found in the @a mint_base_dir.
+ *
+ * @param mint_base_dir base directory for the mint,
+ *                      the signing keys must be in the #DIR_DENOMKEYS
+ *                      subdirectory
+ * @param it function to call on each denomination key found
+ * @param it_cls closure for @a it
+ * @return -1 on error, 0 if no files were found, otherwise
+ *         a positive number (however, even with a positive
+ *         number it is possible that @a it was never called
+ *         as maybe none of the files were well-formed)
+ */
 int
 TALER_MINT_denomkeys_iterate (const char *mint_base_dir,
                               TALER_MINT_DenomkeyIterator it,
@@ -286,19 +321,18 @@ TALER_MINT_denomkeys_iterate (const char *mint_base_dir,
   char *dir;
   size_t len;
   struct DenomkeysIterateContext dic;
+  int ret;
 
-  len = GNUNET_asprintf (&dir,
-                         "%s" DIR_SEPARATOR_STR DIR_DENOMKEYS,
-                         mint_base_dir);
-  GNUNET_assert (len > 0);
-
+  GNUNET_asprintf (&dir,
+                   "%s" DIR_SEPARATOR_STR DIR_DENOMKEYS,
+                   mint_base_dir);
   dic.it = it;
   dic.it_cls = it_cls;
-
-  // scan over alias dirs
-  return GNUNET_DISK_directory_scan (dir,
-                                     &denomkeys_iterate_topdir_iter,
-                                     &dic);
+  ret = GNUNET_DISK_directory_scan (dir,
+                                    &denomkeys_iterate_topdir_iter,
+                                    &dic);
+  GNUNET_free (dir);
+  return ret;
 }
 
 
diff --git a/src/mint/key_io.h b/src/mint/key_io.h
index ae7f183e4..aa59213c3 100644
--- a/src/mint/key_io.h
+++ b/src/mint/key_io.h
@@ -19,9 +19,6 @@
  * @author Florian Dold
  * @author Benedikt Mueller
  * @author Christian Grothoff
- *
- * TODO:
- * - document better
  */
 #ifndef KEY_IO_H
 #define KEY_IO_H
@@ -30,59 +27,64 @@
 #include "taler_signatures.h"
 
 /**
- *
+ * Subdirectroy under the mint's base directory which contains
+ * the mint's signing keys.
  */
 #define DIR_SIGNKEYS "signkeys"
 
 /**
- *
+ * Subdirectory under the mint's base directory which contains
+ * the mint's denomination keys.
  */
 #define DIR_DENOMKEYS "denomkeys"
 
 
 /**
- * On disk format used for a mint signing key.
- * Includes the private key followed by the signed
- * issue message.
+ * On disk format used for a mint signing key.  Signing keys are used
+ * by the mint to affirm its messages, but not to create coins.
+ * Includes the private key followed by the public information about
+ * the signing key.
  */
 struct TALER_MINT_SignKeyIssuePriv
 {
   /**
-   * FIXME.
+   * Private key part of the mint's signing key.
    */
   struct GNUNET_CRYPTO_EddsaPrivateKey signkey_priv;
 
   /**
-   * FIXME.
+   * Public information about a mint signing key.
    */
   struct TALER_MINT_SignKeyIssue issue;
 };
 
 
 /**
- * FIXME.
+ * All information about a denomination key (which is used to
+ * sign coins into existence).
  */
 struct TALER_MINT_DenomKeyIssuePriv
 {
   /**
-   * The private key of the denomination.  Will be NULL if the private key is
-   * not available.
+   * The private key of the denomination.  Will be NULL if the private
+   * key is not available (this is the case after the key has expired
+   * for signing coins, but is still valid for depositing coins).
    */
   struct GNUNET_CRYPTO_rsa_PrivateKey *denom_priv;
 
   /**
-   * FIXME.
+   * Public information about a denomination key.
    */
   struct TALER_MINT_DenomKeyIssue issue;
 };
 
 
 /**
- * Iterator for sign keys.
+ * Iterator over signing keys.
  *
  * @param cls closure
  * @param filename name of the file the key came from
- * @param ski the sign key issue
+ * @param ski the sign key
  * @return #GNUNET_OK to continue to iterate,
  *  #GNUNET_NO to stop iteration with no error,
  *  #GNUNET_SYSERR to abort iteration with error!
@@ -94,10 +96,10 @@ typedef int
 
 
 /**
- * Iterator for denomination keys.
+ * Iterator over denomination keys.
  *
  * @param cls closure
- * @param dki the denomination key issue
+ * @param dki the denomination key
  * @param alias coin alias
  * @return #GNUNET_OK to continue to iterate,
  *  #GNUNET_NO to stop iteration with no error,
@@ -111,12 +113,16 @@ typedef int
 
 
 /**
- * FIXME
+ * Call @a it for each signing key found in the @a mint_base_dir.
  *
- * @param mint_base_dir
- * @param it
+ * @param mint_base_dir base directory for the mint,
+ *                      the signing keys must be in the #DIR_SIGNKEYS
+ *                      subdirectory
+ * @param it function to call on each signing key
  * @param it_cls closure for @a it
- * @return
+ * @return number of files found (may not match
+ *         number of keys given to @a it as malformed
+ *         files are simply skipped), -1 on error
  */
 int
 TALER_MINT_signkeys_iterate (const char *mint_base_dir,
@@ -125,12 +131,17 @@ TALER_MINT_signkeys_iterate (const char *mint_base_dir,
 
 
 /**
- * FIXME
+ * Call @a it for each denomination key found in the @a mint_base_dir.
  *
- * @param mint_base_dir
- * @param it
+ * @param mint_base_dir base directory for the mint,
+ *                      the signing keys must be in the #DIR_DENOMKEYS
+ *                      subdirectory
+ * @param it function to call on each denomination key found
  * @param it_cls closure for @a it
- * @return
+ * @return -1 on error, 0 if no files were found, otherwise
+ *         a positive number (however, even with a positive
+ *         number it is possible that @a it was never called
+ *         as maybe none of the files were well-formed)
  */
 int
 TALER_MINT_denomkeys_iterate (const char *mint_base_dir,
@@ -139,7 +150,7 @@ TALER_MINT_denomkeys_iterate (const char *mint_base_dir,
 
 
 /**
- * Exports a denomination key to the given file
+ * Exports a denomination key to the given file.
  *
  * @param filename the file where to write the denomination key
  * @param dki the denomination key
@@ -151,10 +162,10 @@ TALER_MINT_write_denom_key (const char *filename,
 
 
 /**
- * Import a denomination key from the given file
+ * Import a denomination key from the given file.
  *
  * @param filename the file to import the key from
- * @param dki pointer to return the imported denomination key
+ * @param[OUT] dki set to the imported denomination key
  * @return #GNUNET_OK upon success; #GNUNET_SYSERR upon failure
  */
 int