librhash: move javadoc comments to header files

Author: rhash

librhash/rhash.c

@@ -47,9 +47,6 @@
 #define RHPR_FORMAT (RHPR_RAW | RHPR_HEX | RHPR_BASE32 | RHPR_BASE64)
 #define RHPR_MODIFIER (RHPR_UPPERCASE | RHPR_REVERSE)
 
-/**
- * Initialize static data of rhash algorithms
- */
 void rhash_library_init(void)
 {
 	rhash_init_algorithms(RHASH_ALL_HASHES);
@@ -58,26 +55,13 @@ void rhash_library_init(void)
 #endif
 }
 
-/**
- * Returns the number of supported hash algorithms.
- *
- * @return the number of supported hash functions
- */
 int RHASH_API rhash_count(void)
 {
 	return rhash_info_size;
 }
 
-/* Lo-level rhash library functions */
+/* LOW-LEVEL LIBRHASH INTERFACE */
 
-/**
- * Allocate and initialize RHash context for calculating hash(es).
- * After initializing rhash_update()/rhash_final() functions should be used.
- * Then the context must be freed by calling rhash_free().
- *
- * @param hash_id union of bit flags, containing ids of hashes to calculate.
- * @return initialized rhash context, NULL on error and errno is set
- */
 RHASH_API rhash rhash_init(unsigned hash_id)
 {
 	unsigned tail_bit_index; /* index of hash_id trailing bit */
@@ -168,11 +152,6 @@ RHASH_API rhash rhash_init(unsigned hash_id)
 	return &rctx->rc; /* return allocated and initialized rhash context */
 }
 
-/**
- * Free RHash context memory.
- *
- * @param ctx the context to free.
- */
 void rhash_free(rhash ctx)
 {
 	rhash_context_ext* const ectx = (rhash_context_ext*)ctx;
@@ -193,12 +172,6 @@ void rhash_free(rhash ctx)
 	free(ectx);
 }
 
-/**
- * Re-initialize RHash context to reuse it.
- * Useful to speed up processing of many small messages.
- *
- * @param ctx context to reinitialize
- */
 RHASH_API void rhash_reset(rhash ctx)
 {
 	rhash_context_ext* const ectx = (rhash_context_ext*)ctx;
@@ -221,15 +194,6 @@ RHASH_API void rhash_reset(rhash ctx)
 	ectx->flags &= ~RCTX_FINALIZED; /* clear finalized state */
 }
 
-/**
- * Calculate hashes of message.
- * Can be called repeatedly with chunks of the message to be hashed.
- *
- * @param ctx the rhash context
- * @param message message chunk
- * @param length length of the message chunk
- * @return 0 on success; On fail return -1 and set errno
- */
 RHASH_API int rhash_update(rhash ctx, const void* message, size_t length)
 {
 	rhash_context_ext* const ectx = (rhash_context_ext*)ctx;
@@ -249,13 +213,6 @@ RHASH_API int rhash_update(rhash ctx, const void* message, size_t length)
 	return 0; /* no error processing at the moment */
 }
 
-/**
- * Finalize hash calculation and optionally store the first hash.
- *
- * @param ctx the rhash context
- * @param first_result optional buffer to store a calculated hash with the lowest available id
- * @return 0 on success; On fail return -1 and set errno
- */
 RHASH_API int rhash_final(rhash ctx, unsigned char* first_result)
 {
 	unsigned i = 0;
@@ -330,34 +287,14 @@ static void rhash_put_digest(rhash ctx, unsigned hash_id, unsigned char* result)
 	}
 }
 
-/**
- * Set the callback function to be called from the
- * rhash_file() and rhash_file_update() functions
- * on processing every file block. The file block
- * size is set internally by rhash and now is 8 KiB.
- *
- * @param ctx rhash context
- * @param callback pointer to the callback function
- * @param callback_data pointer to data passed to the callback
- */
 RHASH_API void rhash_set_callback(rhash ctx, rhash_callback_t callback, void* callback_data)
 {
 	((rhash_context_ext*)ctx)->callback = (void*)callback;
 	((rhash_context_ext*)ctx)->callback_data = callback_data;
 }
 
+/* HIGH-LEVEL LIBRHASH INTERFACE */
 
-/* hi-level message hashing interface */
-
-/**
- * Compute a hash of the given message.
- *
- * @param hash_id id of hash sum to compute
- * @param message the message to process
- * @param length message length
- * @param result buffer to receive binary hash string
- * @return 0 on success, -1 on error
- */
 RHASH_API int rhash_msg(unsigned hash_id, const void* message, size_t length, unsigned char* result)
 {
 	rhash ctx;
@@ -370,17 +307,6 @@ RHASH_API int rhash_msg(unsigned hash_id, const void* message, size_t length, un
 	return 0;
 }
 
-/**
- * Hash a file or stream. Multiple hashes can be computed.
- * First, inintialize ctx parameter with rhash_init() before calling
- * rhash_file_update(). Then use rhash_final() and rhash_print()
- * to retrive hash values. Finaly call rhash_free() on ctx
- * to free allocated memory or call rhash_reset() to reuse ctx.
- *
- * @param ctx rhash context
- * @param fd descriptor of the file to hash
- * @return 0 on success, -1 on error and errno is set
- */
 RHASH_API int rhash_file_update(rhash ctx, FILE* fd)
 {
 	rhash_context_ext* const ectx = (rhash_context_ext*)ctx;
@@ -423,14 +349,6 @@ RHASH_API int rhash_file_update(rhash ctx, FILE* fd)
 	return res;
 }
 
-/**
- * Compute a single hash for given file.
- *
- * @param hash_id id of hash sum to compute
- * @param filepath path to the file to hash
- * @param result buffer to receive hash value with the lowest requested id
- * @return 0 on success, -1 on error and errno is set
- */
 RHASH_API int rhash_file(unsigned hash_id, const char* filepath, unsigned char* result)
 {
 	FILE* fd;
@@ -461,14 +379,6 @@ RHASH_API int rhash_file(unsigned hash_id, const char* filepath, unsigned char*
 #ifdef _WIN32 /* windows only function */
 #include <share.h>
 
-/**
- * Compute a single hash for given file.
- *
- * @param hash_id id of hash sum to compute
- * @param filepath path to the file to hash
- * @param result buffer to receive hash value with the lowest requested id
- * @return 0 on success, -1 on error, -1 on error and errno is set
- */
 RHASH_API int rhash_wfile(unsigned hash_id, const wchar_t* filepath, unsigned char* result)
 {
 	FILE* fd;
@@ -514,64 +424,32 @@ const rhash_info* rhash_info_by_id(unsigned hash_id)
 	return rhash_info_table[rhash_ctz(hash_id)].info;
 }
 
-/**
- * Detect default digest output format for given hash algorithm.
- *
- * @param hash_id the id of hash algorithm
- * @return 1 for base32 format, 0 for hexadecimal
- */
 RHASH_API int rhash_is_base32(unsigned hash_id)
 {
 	/* fast method is just to test a bit-mask */
 	return ((hash_id & (RHASH_TTH | RHASH_AICH)) != 0);
 }
 
-/**
- * Returns size of binary digest for given hash algorithm.
- *
- * @param hash_id the id of hash algorithm
- * @return digest size in bytes
- */
 RHASH_API int rhash_get_digest_size(unsigned hash_id)
 {
 	hash_id &= RHASH_ALL_HASHES;
 	if (hash_id == 0 || (hash_id & (hash_id - 1)) != 0) return -1;
 	return (int)rhash_info_table[rhash_ctz(hash_id)].info->digest_size;
 }
 
-/**
- * Returns length of digest hash string in default output format.
- *
- * @param hash_id the id of hash algorithm
- * @return the length of hash string
- */
 RHASH_API int rhash_get_hash_length(unsigned hash_id)
 {
 	const rhash_info* info = rhash_info_by_id(hash_id);
 	return (int)(info ? (info->flags & F_BS32 ?
 		BASE32_LENGTH(info->digest_size) : info->digest_size * 2) : 0);
 }
 
-/**
- * Returns a name of given hash algorithm.
- *
- * @param hash_id the id of hash algorithm
- * @return algorithm name
- */
 RHASH_API const char* rhash_get_name(unsigned hash_id)
 {
 	const rhash_info* info = rhash_info_by_id(hash_id);
 	return (info ? info->name : 0);
 }
 
-/**
- * Returns a name part of magnet urn of the given hash algorithm.
- * Such magnet_name is used to generate a magnet link of the form
- * urn:&lt;magnet_name&gt;=&lt;hash_value&gt;.
- *
- * @param hash_id the id of hash algorithm
- * @return name
- */
 RHASH_API const char* rhash_get_magnet_name(unsigned hash_id)
 {
 	const rhash_info* info = rhash_info_by_id(hash_id);
@@ -617,20 +495,6 @@ static size_t rhash_get_magnet_url_size(const char* filepath,
 	return size;
 }
 
-/**
- * Print magnet link with given filepath and calculated hash sums into the
- * output buffer. The hash_mask can limit which hash values will be printed.
- * The function returns the size of the required buffer.
- * If output is NULL the .
- *
- * @param output a string buffer to receive the magnet link or NULL
- * @param filepath the file path to be printed or NULL
- * @param context algorithms state
- * @param hash_mask bit mask of the hash sums to add to the link
- * @param flags   can be combination of bits RHPR_UPPERCASE, RHPR_NO_MAGNET,
- *                RHPR_FILESIZE
- * @return number of written characters, including terminating '\0' on success, 0 on fail
- */
 RHASH_API size_t rhash_print_magnet(char* output, const char* filepath,
 	rhash context, unsigned hash_mask, int flags)
 {
@@ -689,19 +553,9 @@ RHASH_API size_t rhash_print_magnet(char* output, const char* filepath,
 	return (output - begin);
 }
 
-/* hash sum output */
 
-/**
- * Print a text presentation of a given hash sum to the specified buffer,
- *
- * @param output a buffer to print the hash to
- * @param bytes a hash sum to print
- * @param size a size of hash sum in bytes
- * @param flags  a bit-mask controlling how to format the hash sum,
- *               can be a mix of the flags: RHPR_RAW, RHPR_HEX, RHPR_BASE32,
- *               RHPR_BASE64, RHPR_UPPERCASE, RHPR_REVERSE
- * @return the number of written characters
- */
+/* HASH SUM OUTPUT INTERFACE */
+
 size_t rhash_print_bytes(char* output, const unsigned char* bytes,
 	size_t size, int flags)
 {
@@ -730,21 +584,6 @@ size_t rhash_print_bytes(char* output, const unsigned char* bytes,
 	return str_len;
 }
 
-/**
- * Print text presentation of a hash sum with given hash_id to the specified
- * output buffer. If the hash_id is zero, then print the hash sum with
- * the lowest id stored in the hash context.
- * The function call fails if the context doesn't include a hash with the
- * given hash_id.
- *
- * @param output a buffer to print the hash to
- * @param context algorithms state
- * @param hash_id id of the hash sum to print or 0 to print the first hash
- *                saved in the context.
- * @param flags  a bitmask controlling how to print the hash. Can contain flags
- *               RHPR_UPPERCASE, RHPR_HEX, RHPR_BASE32, RHPR_BASE64, etc.
- * @return the number of written characters on success or 0 on fail
- */
 size_t RHASH_API rhash_print(char* output, rhash context, unsigned hash_id, int flags)
 {
 	const rhash_info* info;
@@ -858,15 +697,6 @@ static rhash_uptr_t process_bt_msg(unsigned msg_id, torrent_ctx* bt, rhash_uptr_
 
 #define PVOID2UPTR(p) ((rhash_uptr_t)(((char*)(p)) + 0))
 
-/**
- * Process a rhash message.
- *
- * @param msg_id message identifier
- * @param dst message destination (can be NULL for generic messages)
- * @param ldata data depending on message
- * @param rdata data depending on message
- * @return message-specific data
- */
 RHASH_API rhash_uptr_t rhash_transmit(unsigned msg_id, void* dst, rhash_uptr_t ldata, rhash_uptr_t rdata)
 {
 	/* for messages working with rhash context */