- Cleaned up the documentation in erasurecode.h to ensure that it

  follows a common format and that it accurately reflects the code.
- Cleaned up liberasurecode_instance_destroy to ensure that the return
  code is correct and that it is not trying to free data that has
  not been removed from the open instances.
- Updated the tests to assert that the liberasurecode_instance_destroy
  method is return correctly.

3 files changed, 50 insertions, 25 deletions

diff --git a/include/erasurecode/erasurecode.h b/include/erasurecode/erasurecode.h
index 1b26b73..da8b3c2 100644
--- a/include/erasurecode/erasurecode.h
+++ b/include/erasurecode/erasurecode.h
@@ -117,7 +117,7 @@ struct ec_args {
  *
  * @param num_backends - pointer to int, size of list returned
  *
- * @returns list of EC backends implemented
+ * @return list of EC backends implemented
  */
 const char ** liberasurecode_supported_backends(int *num_backends);
 
@@ -127,7 +127,7 @@ const char ** liberasurecode_supported_backends(int *num_backends);
  *
  * @param num_checksum_types - pointer to int, size of list returned
  *
- * @returns list of checksum types supported for fragment data
+ * @return list of checksum types supported for fragment data
  */
 const char ** liberasurecode_supported_checksum_types(int *num_checksum_types);
 
@@ -148,7 +148,7 @@ const char ** liberasurecode_supported_checksum_types(int *num_checksum_types);
  *          null_args - arguments for the null backend
  *          flat_xor_hd, jerasure do not require any special args
  *      
- * @returns liberasurecode instance descriptor (int > 0)
+ * @return liberasurecode instance descriptor (int > 0)
  */
 int liberasurecode_instance_create(const char *backend_name,
                                    struct ec_args *args);
@@ -156,7 +156,9 @@ int liberasurecode_instance_create(const char *backend_name,
 /**
  * Close a liberasurecode instance
  *
- * @param liberasurecode descriptor to close
+ * @param desc - liberasurecode descriptor to close
+ *
+ * @return 0 on success, otherwise non-zero error code
  */
 int liberasurecode_instance_destroy(int desc);
 
@@ -195,6 +197,7 @@ int liberasurecode_encode(int desc,
  *        fragments (char *), allocated by liberasurecode_encode
  * @param encoded_parity - (char **) array of m parity
  *        fragments (char *), allocated by liberasurecode_encode
+ *
  * @return 0 in success; -error otherwise
  */
 int liberasurecode_encode_cleanup(int desc, char **encoded_data, char **encoded_parity);
@@ -229,16 +232,16 @@ int liberasurecode_decode(int desc,
  *
  * @param desc - liberasurecode descriptor/handle
  *        from liberasurecode_instance_create()
- * @param data - (char *) buffer of data decoded by
- *        librasurecode_decode
- * @return 0 in success; -error otherwise
+ * @param data - (char *) buffer of data decoded by librasurecode_decode
+ *
+ * @return 0 on success; -error otherwise
  */
 int liberasurecode_decode_cleanup(int desc, char *data);
 
 /**
  * Reconstruct a missing fragment from a subset of available fragments
  *
- * @param desc - liberasurecode descriptor/handle
+ * @param desc - liberasurecode descriptor/handle 
  *        from liberasurecode_instance_create()
  * @param available_fragments - erasure encoded fragments
  * @param num_fragments - number of fragments being passed in
@@ -256,8 +259,17 @@ int liberasurecode_reconstruct_fragment(int desc,
 
 /**
  * Determine which fragments are needed to reconstruct some subset
- * of missing fragments.  Returns a list of lists (as bitmaps)
- * of fragments required to reconstruct missing indexes.
+ * of missing fragments.  The two lists passed into the method (missing_idxs,
+ * and fragments_needed), must be allocated by the user.
+ *
+ * @param desc - liberasurecode descriptor/handle 
+ *        from liberasurecode_instance_create()
+ * @param missing_idxs - -1 terminated list of missing indexes
+ * @param fragements_needed - integer array of length at least k + 1, on
+ *        successful completion, this array will be a -1 terminated list of
+ *        required fragment indexes.
+ *
+ * @return 0 on success, non-zero on error
  */
 int liberasurecode_fragments_needed(int desc,
         int *missing_idxs, int *fragments_needed);
@@ -288,9 +300,10 @@ fragment_metadata
  * @param desc - liberasurecode descriptor/handle
  *        from liberasurecode_instance_create()
  * @param fragment - fragment data pointer
+ * @param fragment_metadata - pointer to allocated buffer of size at least
+ *        sizeof(struct fragment_metadata) to hold fragment metadata struct
  *
- * @param fragment_metadata - pointer to output fragment metadata struct
- *          (reference passed by the user)
+ * @return 0 on success, non-zero on error
  */
 int liberasurecode_get_fragment_metadata(int desc,
         char *fragment, fragment_metadata_t *fragment_metadata);
@@ -301,10 +314,9 @@ int liberasurecode_get_fragment_metadata(int desc,
  * @param desc - liberasurecode descriptor/handle
  *        from liberasurecode_instance_create()
  * @param fragments - fragments part of the EC stripe to verify
- * @num_fragments - number of fragments part of the EC stripe
+ * @param num_fragments - number of fragments part of the EC stripe
  *
- * @ returns 1 if stripe checksum verification is successful
- *           0 otherwise
+ * @return 1 if stripe checksum verification is successful, 0 otherwise
  */
 int liberasurecode_verify_stripe_metadata(int desc,
         char **fragments, int num_fragments);
@@ -317,12 +329,23 @@ int liberasurecode_verify_stripe_metadata(int desc,
  * to be algined with the word size (w) and the last fragment also
  * needs to be aligned.  This computes the sum of the algined fragment
  * sizes for a given buffer to encode.
+ *
+ * @param desc - liberasurecode descriptor/handle
+ *        from liberasurecode_instance_create()
+ * @param data_len - original data length in bytes
+ *
+ * @return aligned length, or -error code on error
  */
 int liberasurecode_get_aligned_data_size(int desc, uint64_t data_len);
  
 /**
  * This will return the minimum encode size, which is the minimum
  * buffer size that can be encoded.
+ * 
+ * @param desc - liberasurecode descriptor/handle
+ *        from liberasurecode_instance_create()
+ *
+ * @return minimum data length length, or -error code on error
  */
 int liberasurecode_get_minimum_encode_size(int desc);
 
diff --git a/src/erasurecode.c b/src/erasurecode.c
index 2a5bd9b..9b41293 100644
--- a/src/erasurecode.c
+++ b/src/erasurecode.c
@@ -93,7 +93,7 @@ int next_backend_desc = 0;
 /**
  * Look up a backend instance by descriptor
  *
- * Returns pointer to a registered liberasurecode instance
+ * @returns pointer to a registered liberasurecode instance
  * The caller must hold active_instances_rwlock
  */
 ec_backend_t liberasurecode_backend_instance_get_by_desc(int desc)
@@ -342,10 +342,12 @@ int liberasurecode_instance_create(const char *backend_name,
  */
 int liberasurecode_instance_destroy(int desc)
 {
-    ec_backend_t instance = liberasurecode_backend_instance_get_by_desc(desc);
+    ec_backend_t instance = NULL;  /* instance to destroy */
+    int rc = 0;                    /* return code */
 
+    instance = liberasurecode_backend_instance_get_by_desc(desc);
     if (NULL == instance)
-        return 0;
+        return EBACKENDNOTAVAIL;
 
     /* Call private exit() for the backend */
     instance->common.ops->exit(instance->desc.backend_desc);
@@ -354,12 +356,12 @@ int liberasurecode_instance_destroy(int desc)
     liberasurecode_backend_close(instance);
 
     /* Remove instace from registry */
-    liberasurecode_backend_instance_unregister(instance);
-
-    /* Cleanup */
-    free(instance);
+    rc = liberasurecode_backend_instance_unregister(instance);
+    if (rc == 0) {
+        free(instance);
+    }
 
-    return 0;
+    return rc;
 }
 
 /**
diff --git a/test/liberasurecode_test.c b/test/liberasurecode_test.c
index cfa24bf..f82a87b 100644
--- a/test/liberasurecode_test.c
+++ b/test/liberasurecode_test.c
@@ -135,7 +135,7 @@ static void test_create_and_destroy_backend(
         return;
     }
     assert(desc > 0);
-    liberasurecode_instance_destroy(desc);
+    assert(0 == liberasurecode_instance_destroy(desc));
 }
 
 static void encode_decode_test_impl(const char *backend,
@@ -177,7 +177,7 @@ static void encode_decode_test_impl(const char *backend,
     assert(memcmp(decoded_data, orig_data, orig_data_size) == 0);
 
     if (desc)
-        liberasurecode_instance_destroy(desc);
+        assert(0 == liberasurecode_instance_destroy(desc));
     free(orig_data);
     if (avail_frags != NULL)
     {