general cleanup

include/mh/hashes.h

@@ -31,7 +31,16 @@ static const int mh_all_hashes[] = {
 
 #define MH_H_COUNT (int)(sizeof(mh_all_hashes) / sizeof(mh_all_hashes[0]))
 
+/**
+ * Given the id, return the hash name
+ * @param hash the id (such as MH_H_SHA1)
+ * @returns the name as text, such as "sha1"
+ */
 const char *mh_hash_name(int hash);
 
-// returns length in bytes or if returns is < 0 it is an error
+/**
+ * Given the id, return the default length
+ * @param hash the id
+ * @returns the default length of that hash
+ */
 int mh_hash_default_length(int hash);

include/mh/multihash.h

@@ -3,25 +3,47 @@
 
 #include <stddef.h>
 
-// returns hash code or error (which is < 0)
+/**
+ * returns hash code or error (which is < 0)
+ * @param mh the multihash
+ * @param len the length of the multihash
+ * @returns errors ( < 0 ) or the multihash
+ */
 int mh_multihash_hash(const unsigned char *multihash, size_t len);
 
-// returns length of multihash or error (which is < 0)
+/***
+ * returns the length of the multihash's data section
+ * @param mh the multihash
+ * @param len the length of the multihash
+ * @returns the length of the data section, or an error if < 0
+ */
 int mh_multihash_length(const unsigned char *multihash, size_t len);
 
-// gives access to raw digest inside multihash buffer
-// returns 0 or negative error
+/**
+ * gives access to raw digest inside multihash buffer
+ * @param multihash the multihash
+ * @param len the length
+ * @param digest the results
+ * @returns error if less than zero, otherwise 0
+ */
 int mh_multihash_digest(unsigned char *multihash, size_t len,
 	 unsigned char **digest, size_t *digest_len);
 
-// returns length in bytes of buffer needed to store multihash
-// with given hashcode and with given digest length
-// returns length or negative error code
+/**
+ * determine the size of the multihash given the data size
+ * @param code currently not used
+ * @param hash_len the data size
+ * @returns hash_len + 2 (until the code parameter (varint) is added
+ */
 int mh_new_length(int code, size_t digest_len);
 
-// writes multihash into a buffer, the buffer needs to be at least
-// mh_new_length() bytes long.
-// returns negative error code or 0
+/***
+ * create a multihash based on some data
+ * @param buffer where to put the multihash
+ * @param code the code
+ * @param digest the data within the multihash
+ * @returns error (if < 0) or 0
+ */
 int mh_new(unsigned char *buffer, int code, const unsigned char *digest,
 	size_t digest_len);
 

src/errors.c

@@ -1,5 +1,10 @@
 #include "mh/errors.h"
 
+/**
+ * Convert an error code into a string
+ * @param code the error code
+ * @returns the error as text
+ */
 const char *mh_error_string(int code) {
 	switch (code) {
 		case MH_E_NO_ERROR:

src/hashes.c

@@ -1,3 +1,7 @@
+/***
+ * Some helpers in identifying hashes
+ */
+
 #include <stdlib.h>
 
 #include "mh/hashes.h"
@@ -26,7 +30,11 @@ static const struct hash_info {
 
 mh_assert_static(sizeof(hash_infos) / sizeof(hash_infos[0]) == MH_H_COUNT);
 
-// Searches for given hash in hash info table
+/**
+ * Given the id, return a struct that shows the id, name, and default length
+ * @param hash the id, such as MH_H_SHA1
+ * @returns a hash_info struct that has an int, const char* and int
+ */
 static const struct hash_info *find_hash(int hash) {
 	// naive search, could be replaced with binary
 	unsigned int i = 0;
@@ -38,12 +46,21 @@ static const struct hash_info *find_hash(int hash) {
 	return NULL;
 }
 
+/**
+ * Given the id, return the hash name
+ * @param hash the id (such as MH_H_SHA1)
+ * @returns the name as text, such as "sha1"
+ */
 const char *mh_hash_name(int hash) {
 	const struct hash_info *info = find_hash(hash);
 	return (info != NULL) ? info->name : NULL;
 }
 
-
+/**
+ * Given the id, return the default length
+ * @param hash the id
+ * @returns the default length of that hash
+ */
 int mh_hash_default_length(int hash) {
 	const struct hash_info *info = find_hash(hash);
 	return (info != NULL) ? info->length : MH_E_UNKNOWN_CODE;

src/main.c

@@ -1,6 +0,0 @@
-#include <stdio.h>
-
-int main(void) {
-	printf("Hello World\n");
-	return 0;
-}

src/multihash.c

@@ -9,6 +9,11 @@
 
 #define VARINT_MASK (1 << 7)
 
+/**
+ * checks the length of a multihash for validity
+ * @param len the length of the multihash
+ * @returns errors or MH_E_NO_ERROR(0)
+ */
 static int check_len(size_t len) {
 	if (len < 1)
 		return MH_E_TOO_SHORT;
@@ -18,6 +23,12 @@ static int check_len(size_t len) {
 	return MH_E_NO_ERROR;
 }
 
+/**
+ * do some general checks on the multihash for validity
+ * @param mh the multihash
+ * @param len the length of the multihash
+ * @returns errors or MH_E_NO_ERROR(0)
+ */
 static int check_multihash(const unsigned char mh[], size_t len) {
 	int err;
 
@@ -33,14 +44,17 @@ static int check_multihash(const unsigned char mh[], size_t len) {
 	}
 
 	err = check_len(mh[1]);
-	if (err)
-		return err;
 
-	return 0;
+	return err;
 }
 
 
-// returns hash code or error (which is < 0)
+/**
+ * returns hash code or error (which is < 0)
+ * @param mh the multihash
+ * @param len the length of the multihash
+ * @returns errors ( < 0 ) or the multihash
+ */
 int mh_multihash_hash(const unsigned char *mh, size_t len) {
 	int err = check_multihash(mh, len);
 	if (err)
@@ -50,7 +64,12 @@ int mh_multihash_hash(const unsigned char *mh, size_t len) {
 }
 
 
-// returns length of multihash or error (which is < 0)
+/***
+ * returns the length of the multihash's data section
+ * @param mh the multihash
+ * @param len the length of the multihash
+ * @returns the length of the data section, or an error if < 0
+ */
 int mh_multihash_length(const unsigned char *mh, size_t len) {
 	int err = check_multihash(mh, len);
 	if (err)
@@ -59,8 +78,13 @@ int mh_multihash_length(const unsigned char *mh, size_t len) {
 	return (int) mh[1];
 }
 
-// gives access to raw digest inside multihash buffer
-// returns 0 or negative error
+/**
+ * gives access to raw digest inside multihash buffer
+ * @param multihash the multihash
+ * @param len the length
+ * @param digest the results
+ * @returns error if less than zero, otherwise 0
+ */
 int mh_multihash_digest(unsigned char *multihash, size_t len, unsigned char **digest,
 		size_t *digest_len) {
 	int err = check_multihash(multihash, len);
@@ -73,6 +97,12 @@ int mh_multihash_digest(unsigned char *multihash, size_t len, unsigned char **di
 	return 0;
 }
 
+/**
+ * determine the size of the multihash given the data size
+ * @param code currently not used
+ * @param hash_len the data size
+ * @returns hash_len + 2 (until the code parameter (varint) is added
+ */
 int mh_new_length(int code, size_t hash_len) {
 	// right now there is no varint support
 	// so length required is 2 + hash_len
@@ -80,6 +110,13 @@ int mh_new_length(int code, size_t hash_len) {
 	return 2 + hash_len;
 }
 
+/***
+ * create a multihash based on some data
+ * @param buffer where to put the multihash
+ * @param code the code
+ * @param digest the data within the multihash
+ * @returns error (if < 0) or 0
+ */
 int mh_new(unsigned char *buffer, int code, const unsigned char *digest,
 	size_t digest_len) {
 	if (code & VARINT_MASK)