docs: refined documentation

cartesi · Apr 9, 2024 · 221f5da · 221f5da
1 parent 163ce5c
commit 221f5da
Show file tree

Hide file tree

Showing 3 changed files with 26 additions and 11 deletions.
diff --git a/sys-utils/libcmt/src/merkle.h b/sys-utils/libcmt/src/merkle.h
@@ -55,16 +55,24 @@ void cmt_merkle_fini(cmt_merkle_t *me);
  *
  * @param [in] me       either a initialized or uninitialized state
  * @param [in] filepath which file to save the merkle state
+ *
  * @return
- * - 0 on success */
+ * |   |                             |
+ * |--:|-----------------------------|
+ * |  0| success                     |
+ * |< 0| failure with a -errno value | */
 int cmt_merkle_load(cmt_merkle_t *me, const char *filepath);
 
 /** Save the a @ref cmt_merkle_t tree to a @p file handle.
  *
  * @param [in] me       either a initialized or uninitialized state
  * @param [in] filepath which file to save the merkle state
+ *
  * @return
- * - 0 on success */
+ * |   |                             |
+ * |--:|-----------------------------|
+ * |  0| success                     |
+ * |< 0| failure with a -errno value | */
 int cmt_merkle_save(cmt_merkle_t *me, const char *filepath);
 
 /** Return number of leaves already in tree
@@ -78,19 +86,27 @@ uint64_t cmt_merkle_get_leaf_count(cmt_merkle_t *me);
  *
  * @param [in,out] me initialized state
  * @param [in] hash   value of the new leaf
+ *
  * @return
- * - 0        success
- * - -ENOBUFS indicates the tree is full */
+ * |          |                                 |
+ * |---------:|---------------------------------|
+ * |         0| success                         |
+ * | -ENOBUFS | indicates that the tree is full |
+ * |       < 0| failure with a -errno value     | */
 int cmt_merkle_push_back(cmt_merkle_t *me, const uint8_t hash[CMT_KECCAK_LENGTH]);
 
 /** Compute the keccak-256 hash of @p data and append it as a leaf node
  *
  * @param [in,out] me     initialized state
  * @param [in]     length size of @p data in bytes
  * @param [in]     data   array of bytes
+ *
  * @return
- * - 0        success
- * - -ENOBUFS indicates that the tree is full */
+ * |          |                                 |
+ * |---------:|---------------------------------|
+ * |         0| success                         |
+ * | -ENOBUFS | indicates that the tree is full |
+ * |       < 0| failure with a -errno value     | */
 int cmt_merkle_push_back_data(cmt_merkle_t *me, size_t length, const void *data);
 
 /** Compute the root hash of the merkle tree

diff --git a/sys-utils/libcmt/src/rollup.c b/sys-utils/libcmt/src/rollup.c
@@ -397,7 +397,6 @@ int cmt_rollup_save_merkle(cmt_rollup_t *me, const char *path) {
     return DBG(cmt_merkle_save(me->merkle, path));
 }
 
-int cmt_rollup_reset_merkle(cmt_rollup_t *me) {
+void cmt_rollup_reset_merkle(cmt_rollup_t *me) {
     cmt_merkle_reset(me->merkle);
-    return 0;
 }
diff --git a/sys-utils/libcmt/src/rollup.h b/sys-utils/libcmt/src/rollup.h
@@ -157,7 +157,7 @@ int cmt_rollup_emit_exception(cmt_rollup_t *me, uint32_t data_length, const void
 /** Read advance state
  *
  * @param [in,out] me      initialized cmt_rollup_t instance
- * @param [in,out] advance cmt_rollup_advance_t instance (maybe uninitialized)
+ * @param [out]    advance cmt_rollup_advance_t instance (may be uninitialized)
  *
  * @return
  * |   |                             |
@@ -169,7 +169,7 @@ int cmt_rollup_read_advance_state(cmt_rollup_t *me, cmt_rollup_advance_t *advanc
 /** Read inspect state
  *
  * @param [in,out] me      initialized cmt_rollup_t instance
- * @param [in,out] inspect cmt_rollup_inspect_t instance (maybe uninitialized)
+ * @param [out]    inspect cmt_rollup_inspect_t instance (may be uninitialized)
  *
  * @return
  * |   |                             |
@@ -229,6 +229,6 @@ int cmt_rollup_save_merkle(cmt_rollup_t *me, const char *path);
 /** Resets the merkle tree to pristine conditions
  *
  * @param [in,out] me      initialized cmt_rollup_t instance */
-int cmt_rollup_reset_merkle(cmt_rollup_t *me);
+void cmt_rollup_reset_merkle(cmt_rollup_t *me);
 
 #endif /* CMT_ROLLUP_H */