Add documentation.

spamsum.c

@@ -33,6 +33,15 @@ static uint8_t b64[] = {0x41, 0x42, 0x43, 0x44, 0x45, 0x46, 0x47, 0x48, 0x49, 0x
                         0x67, 0x68, 0x69, 0x6A, 0x6B, 0x6C, 0x6D, 0x6E, 0x6F, 0x70, 0x71, 0x72, 0x73, 0x74, 0x75, 0x76,
                         0x77, 0x78, 0x79, 0x7A, 0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38, 0x39, 0x2B, 0x2F};
 
+/**
+ * @brief Initializes the SpamSum checksum algorithm.
+ *
+ * This function initializes the state variables required for the SpamSum
+ * checksum algorithm. It prepares the algorithm to calculate the checksum
+ * for a new data set.
+ *
+ * @return Pointer to a structure containing the checksum state.
+ */
 AARU_EXPORT spamsum_ctx* AARU_CALL spamsum_init(void)
 {
     spamsum_ctx* ctx = (spamsum_ctx*)malloc(sizeof(spamsum_ctx));
@@ -47,6 +56,17 @@ AARU_EXPORT spamsum_ctx* AARU_CALL spamsum_init(void)
     return ctx;
 }
 
+/**
+ * @brief Updates the SpamSum checksum with new data.
+ *
+ * This function updates the SpamSum checksum.
+ *
+ * @param ctx Pointer to the SpamSum context structure.
+ * @param data Pointer to the input data buffer.
+ * @param len The length of the input data buffer.
+ *
+ * @returns 0 on success, -1 on error.
+ */
 AARU_EXPORT int AARU_CALL spamsum_update(spamsum_ctx* ctx, const uint8_t* data, uint32_t len)
 {
     int i;
@@ -59,6 +79,14 @@ AARU_EXPORT int AARU_CALL spamsum_update(spamsum_ctx* ctx, const uint8_t* data,
     return 0;
 }
 
+/**
+ * @brief Frees the resources allocated for the SpamSum checksum context.
+ *
+ * This function should be called to release the memory used by the SpamSum checksum
+ * context structure after it is no longer needed.
+ *
+ * @param ctx The SpamSum checksum context structure, to be freed.
+ */
 AARU_EXPORT void AARU_CALL spamsum_free(spamsum_ctx* ctx)
 {
     if(ctx) free(ctx);
@@ -175,6 +203,17 @@ AARU_LOCAL inline void fuzzy_try_fork_blockhash(spamsum_ctx* ctx)
     ++ctx->bh_end;
 }
 
+/**
+ * @brief Finalizes the calculation of the SpamSum checksum.
+ *
+ * This function finalizes the calculation of the SpamSum checksum and returns
+ * its value.
+ *
+ * @param[in] ctx Pointer to the SpamSum context structure.
+ * @param[out] result Pointer to a buffer to store the checksum value.
+ *
+ * @returns 0 on success, -1 on error.
+ */
 AARU_EXPORT int AARU_CALL spamsum_final(spamsum_ctx* ctx, uint8_t* result)
 {
     uint32_t bi     = ctx->bh_start;