From b8729744ecc0b60680fd731f8f45bb86a839d997 Mon Sep 17 00:00:00 2001
From: Michal Vaner <vorner@ucw.cz>
Date: Sat, 13 Sep 2008 21:28:50 +0200
Subject: [PATCH] ucw. docs: Update hash documentation

More info about non-crypto hashes
Better links inside the page
---
 ucw/doc/hash.txt | 23 ++++++++++++++++-------
 ucw/hashfunc.h   | 30 +++++++++++++++---------------
 2 files changed, 31 insertions(+), 22 deletions(-)

diff --git a/ucw/doc/hash.txt b/ucw/doc/hash.txt
index bac3b9c9..bcdbb7e3 100644
--- a/ucw/doc/hash.txt
+++ b/ucw/doc/hash.txt
@@ -6,33 +6,35 @@ Libucw contains two cryptographic hash algorithms: MD5 (RFC 1321) and SHA1 (RFC
 
 There are non-cryptographic hashes as well.
 
-Cryptographic ones
-------------------
+<<crypto,Cryptographic ones>>:
 
 - <<md5,MD5>>
 - <<sha1,SHA1>>
 - <<sha1:sha1_hmac(),SHA1_HMAC>>
 - <<usage,Common usage>>
 
-Non-cryptographic ones
-----------------------
+<<nocrypto,Non-cryptographic ones>>:
 
 - <<strhash,String & block hashes>>
 - <<inthash,Integer hashes>>
 
+[[crypto]]
+Cryptographic hashes
+--------------------
+
 [[md5]]
 MD5
----
+~~~
 !!ucw/md5.h
 
 [[sha1]]
 SHA1
-----
+~~~~
 !!ucw/sha1.h
 
 [[usage]]
 Common usage
-------------
+~~~~~~~~~~~~
 
 There are two ways you can use the hashing routines.
 
@@ -61,4 +63,11 @@ SHA1 has the same interface, so the same two ways apply.
 
 See also <<string:mem_to_hex()>>.
 
+[[nocrypto]]
+Non-cryptographic hashes
+------------------------
+
+All these functions expect to be moduled by the size of a hash table.
+The size should be a prime number (it gives better distribution).
+
 !!ucw/hashfunc.h
diff --git a/ucw/hashfunc.h b/ucw/hashfunc.h
index b67321c1..5f9dd885 100644
--- a/ucw/hashfunc.h
+++ b/ucw/hashfunc.h
@@ -13,32 +13,32 @@
 
 #include "ucw/lib.h"
 
-/*** == String hashes [[strhash]] ***/
+/*** === String hashes [[strhash]] ***/
 
-/* The following functions need str to be aligned to uns.  */
-uns str_len_aligned(const char *str) PURE; /** Get the string length (actually hash function too). The string must be aligned to uns. For unaligned see str_len(). **/
-uns hash_string_aligned(const char *str) PURE; /** Hash the string. The string must be aligned to uns. For unaligned see hash_string(). **/
-uns hash_block_aligned(const byte *str, uns len) PURE; /** Hash arbitrary data. They must be aligned to uns. For unaligned see hash_block(). **/
+/* The following functions need str to be aligned to `sizeof(uns).  */
+uns str_len_aligned(const char *str) PURE; /** Get the string length (not a really useful hash function, but there is no better place for it). The string must be aligned to `sizeof(uns)`. For unaligned see str_len(). **/
+uns hash_string_aligned(const char *str) PURE; /** Hash the string. The string must be aligned to `sizeof(uns)`. For unaligned see hash_string(). **/
+uns hash_block_aligned(const byte *str, uns len) PURE; /** Hash arbitrary data. They must be aligned to `sizeof(uns)`. For unaligned see hash_block(). **/
 
 #ifdef	CPU_ALLOW_UNALIGNED
 #define	str_len(str)		str_len_aligned(str)
 #define	hash_string(str)	hash_string_aligned(str)
 #define	hash_block(str, len)	hash_block_aligned(str, len)
 #else
-uns str_len(const char *str) PURE; /** Get the string length (actually a hash function too). If you know it is aligned to uns, you can use faster str_len_aligned(). **/
-uns hash_string(const char *str) PURE; /** Hash the string. If it is aligned to uns, you can use faster hash_string_aligned(). **/
-uns hash_block(const byte *str, uns len) PURE; /** Hash arbitrary data. If they are aligned to uns, use faster hash_block_aligned(). **/
+uns str_len(const char *str) PURE; /** Get the string length. If you know it is aligned to `sizeof(uns)`, you can use faster str_len_aligned(). **/
+uns hash_string(const char *str) PURE; /** Hash the string. If it is aligned to `sizeof(uns)`, you can use faster hash_string_aligned(). **/
+uns hash_block(const byte *str, uns len) PURE; /** Hash arbitrary data. If they are aligned to `sizeof(uns)`, use faster hash_block_aligned(). **/
 #endif
 
-uns hash_string_nocase(const char *str) PURE; /** Hash the string in a case insensitive way. **/
+uns hash_string_nocase(const char *str) PURE; /** Hash the string in a case insensitive way. Works only with ASCII characters. **/
 
-/*** == Integer hashes [[inthash]] ***/
+/*** === Integer hashes [[inthash]] ***/
 
-/*
- *  We hash integers by multiplying by a reasonably large prime with
- *  few ones in its binary form (to gave the compiler the possibility
- *  of using shifts and adds on architectures where multiplication
- *  instructions are slow).
+/***
+ * We hash integers by multiplying by a reasonably large prime with
+ * few ones in its binary form (to give the compiler the possibility
+ * of using shifts and adds on architectures where multiplication
+ * instructions are slow).
  */
 static inline uns CONST hash_u32(uns x) { return 0x01008041*x; } /** Hash a 32 bit unsigned integer. **/
 static inline uns CONST hash_u64(u64 x) { return hash_u32((uns)x ^ (uns)(x >> 32)); } /** Hash a 64 bit unsigned integer. **/
-- 
2.39.5