From 078dd50e9e9d322db3f5ac8d0c434ebeeac10a79 Mon Sep 17 00:00:00 2001
From: Martin Mares <mj@ucw.cz>
Date: Sun, 18 Mar 2012 23:05:21 +0100
Subject: [PATCH] CRC: Documentation

---
 ucw/crc.h        | 25 +++++++++++++++++--------
 ucw/doc/hash.txt | 34 ++++++++++++++++++++++++----------
 2 files changed, 41 insertions(+), 18 deletions(-)

diff --git a/ucw/crc.h b/ucw/crc.h
index 0e3d0137..28d59acf 100644
--- a/ucw/crc.h
+++ b/ucw/crc.h
@@ -16,7 +16,7 @@
  *	Adapted for LibUCW by Martin Mares <mj@ucw.cz> in 2012.
  */
 
-/*
+/**
  * Internal CRC calculator context.
  * You should use it just as an opaque handle only.
  */
@@ -25,23 +25,32 @@ typedef struct crc32_context {
   void (*update_func)(struct crc32_context *ctx, const byte *buf, uns len);
 } crc32_context;
 
+/**
+ * Initialize new calculation of CRC in a given context.
+ * @crc_mode selects which algorithm should be used.
+ **/
 void crc32_init(crc32_context *ctx, uns crc_mode);
 
+/**
+ * Algorithm used for CRC calculation. The algorithms differ by the amount
+ * of precomputed tables they use. Bigger tables imply faster calculation
+ * at the cost of an increased cache footprint.
+ **/
 enum crc_mode {
-  CRC_MODE_DEFAULT,
-  CRC_MODE_SMALL,
-  CRC_MODE_BIG,
+  CRC_MODE_DEFAULT,		/* Default algorithm (4K table) */
+  CRC_MODE_SMALL,		/* Optimize for small data (1K table) */
+  CRC_MODE_BIG,			/* Optimize for large data (8K table) */
   CRC_MODE_MAX,
 };
 
-static inline void
-crc32_update(crc32_context *ctx, const byte *buf, uns len)
+/** Feed @len bytes starting at @buf to the CRC calculator. **/
+static inline void crc32_update(crc32_context *ctx, const byte *buf, uns len)
 {
   ctx->update_func(ctx, buf, len);
 }
 
-static inline u32
-crc32_final(crc32_context *ctx)
+/** Finish calculation and return the CRC value. **/
+static inline u32 crc32_final(crc32_context *ctx)
 {
   return ctx->state ^ 0xffffffff;
 }
diff --git a/ucw/doc/hash.txt b/ucw/doc/hash.txt
index 3e01b941..788a382c 100644
--- a/ucw/doc/hash.txt
+++ b/ucw/doc/hash.txt
@@ -1,22 +1,21 @@
 Hashing routines
 ================
 
-Libucw contains two cryptographic hash algorithms: MD5 (RFC 1321) and SHA1 (RFC
-3174). A SHA1-HMAC (RFC 2104) message authentication is available.
+LibUCW contains implementations of several hash algorithms.
 
-There are non-cryptographic hashes as well.
+<<crypto,Cryptographic hashes>>:
 
-<<crypto,Cryptographic ones>>:
-
-- <<md5,MD5>>
-- <<sha1,SHA1>>
-- <<sha1:sha1_hmac(),SHA1_HMAC>>
+- <<md5,MD5>> (RFC 1321)
+- <<sha1,SHA1>> (RFC 3174)
+- <<hash:sha1_hmac(),SHA1_HMAC message authentication>> (RFC 2104)
 - <<usage,Common usage>>
 
 <<checksum,Checksums>>:
+
 - <<crypto:adler,Adler-32>>
+- <<crc,CRC>>
 
-<<nocrypto,Non-cryptographic ones>>:
+<<nocrypto,Non-cryptographic hashes>>:
 
 - <<strhash,String & block hashes>>
 - <<inthash,Integer hashes>>
@@ -73,8 +72,23 @@ Checksums
 Their purpose is checking against random data changes, hardware
 failures and alike. They are not to be used against aimed attacks.
 
+Adler-32
+~~~~~~~~
+
 The <<compress:adler,Adler-32 checksum>> is documented in the
-<<compression,compression capter>>.
+<<compress:,compression capter>>.
+
+CRC-32
+~~~~~~
+
+32-bit Cyclic Redundancy Check with the polynomial suggested by
+Castagnoli et al.: Optimization of Cyclic Redundancy-Check Codes
+with 24 and 32 Parity Bits", IEEE Trans. on Communications, Vol. 41,
+No. 6, 1993.
+
+The interface is similar to the one we use for the cryptographic hashes.
+
+!!ucw/crc.h
 
 [[nocrypto]]
 Non-cryptographic hashes
-- 
2.39.2