From 90676f283e64e478958fc690a9c2b2472bb0f9e8 Mon Sep 17 00:00:00 2001
From: Martin Mares <mj@ucw.cz>
Date: Thu, 11 Sep 2008 23:18:29 +0200
Subject: [PATCH] A couple of fixes to hash function documentation.

---
 ucw/doc/hash.txt |  6 +++---
 ucw/md5.h        | 11 +++++++----
 ucw/sha1.h       | 12 +++++++-----
 3 files changed, 17 insertions(+), 12 deletions(-)

diff --git a/ucw/doc/hash.txt b/ucw/doc/hash.txt
index b28c42a7..22459c1c 100644
--- a/ucw/doc/hash.txt
+++ b/ucw/doc/hash.txt
@@ -1,12 +1,12 @@
 Hashing routines
 ================
 
-Libucw contains two hash algorithms, MD5 (RFC 1321) and SHA1 (RFC
+Libucw contains two cryptographic hash algorithms: MD5 (RFC 1321) and SHA1 (RFC
 3174).
 
 - <<md5,MD5>>
 - <<sha1,SHA1>>
-- <<usage,Usage>>
+- <<usage,Common usage>>
 
 [[md5]]
 MD5
@@ -45,6 +45,6 @@ There are two ways you can use the hashing routines.
   byte output[MD5_SIZE];
   memcpy(output, md5_final(&c), MD5_SIZE);
 
-SHA1 has the same interface, so both ways work to it as well.
+SHA1 has the same interface, so the same two ways apply.
 
 See also <<string:mem_to_hex()>>.
diff --git a/ucw/md5.h b/ucw/md5.h
index 20dafb4d..400c8752 100644
--- a/ucw/md5.h
+++ b/ucw/md5.h
@@ -9,7 +9,7 @@
 
 /**
  * Internal MD5 hash state.
- * You can use it just as a opaque handle.
+ * You should use it just as an opaque handle only.
  */
 typedef struct {
 	u32 buf[4];
@@ -22,22 +22,25 @@ void md5_init(md5_context *context); /** Initialize the MD5 hashing algorithm in
  * Push another @len bytes of data from @buf to the MD5 hash
  * represented by @context. You can call it multiple time on the same
  * @context without reinitializing it and the result will be the same
- * as you concatenated all the data together and fed them here all at
+ * as if you concatenated all the data together and fed them here all at
  * once.
  */
 void md5_update(md5_context *context, const byte *buf, uns len);
 /**
  * Call this after the last md5_update(). It will terminate the
- * algorithm and return pointer to the result.
+ * algorithm and return a pointer to the result.
  *
  * Note that the data it points to are stored inside the @context, so
  * if you use it to compute another hash or it ceases to exist, the
  * pointer becomes invalid.
+ *
+ * To convert the hash to its usual hexadecimal representation, see
+ * <<string:mem_to_hex()>>.
  */
 byte *md5_final(md5_context *context);
 
 /**
- * This is the core routine of MD5 algorithm. It takes 16 longwords of
+ * This is the core routine of the MD5 algorithm. It takes 16 longwords of
  * data in @in and transforms the hash in @buf according to them.
  *
  * You probably do not want to call this one directly.
diff --git a/ucw/sha1.h b/ucw/sha1.h
index d9ca009e..ce8fca32 100644
--- a/ucw/sha1.h
+++ b/ucw/sha1.h
@@ -16,8 +16,7 @@
 
 /**
  * Internal SHA1 state.
- * You can consider it an opaque handle, if you want just hash
- * functions.
+ * You should use it just as an opaque handle only.
  */
 typedef struct {
   u32 h0,h1,h2,h3,h4;
@@ -37,15 +36,18 @@ void sha1_init(sha1_context *hd); /** Initialize new algorithm run in the @hd co
 void sha1_update(sha1_context *hd, const byte *inbuf, uns inlen);
 /**
  * No more sha1_update() calls will be done. This terminates the hash
- * and returns pointer to it.
+ * and returns a pointer to it.
  *
- * Note the pointer points into data in the @hd context. If it ceases
+ * Note that the pointer points into data in the @hd context. If it ceases
  * to exist, the pointer becomes invalid.
+ *
+ * To convert the hash to its usual hexadecimal representation, see
+ * <<string:mem_to_hex()>>.
  */
 byte *sha1_final(sha1_context *hd);
 
 /**
- * Convenience one-shot function for SHA1 hash.
+ * A convenience one-shot function for SHA1 hash.
  * It is equivalent to this snippet of code:
  *
  *  sha1_context hd;
-- 
2.39.2