From 5f30110e2c49be3ebe764d9cca7314b6b8cb448b Mon Sep 17 00:00:00 2001
From: Nahua <kangnahua@gmail.com>
Date: Sun, 15 Jan 2023 21:37:09 +0100
Subject: [PATCH] hash: document all public functions (#16987)

---
 vlib/hash/crc32/crc32.v | 8 ++++++--
 vlib/hash/wyhash.c.v    | 4 ++++
 vlib/hash/wyhash.v      | 1 +
 3 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/vlib/hash/crc32/crc32.v b/vlib/hash/crc32/crc32.v
index 38c54719a7..0604038fb3 100644
--- a/vlib/hash/crc32/crc32.v
+++ b/vlib/hash/crc32/crc32.v
@@ -23,6 +23,8 @@ mut:
 	table []u32
 }
 
+// generate_table populates a 256-word table from the specified polynomial `poly`
+// to represent the polynomial for efficient processing.
 fn (mut c Crc32) generate_table(poly int) {
 	for i in 0 .. 256 {
 		mut crc := u32(i)
@@ -45,18 +47,20 @@ fn (c &Crc32) sum32(b []u8) u32 {
 	return ~crc
 }
 
+// checksum returns the CRC-32 checksum of data `b` by using the polynomial represented by
+// `c`'s table.
 pub fn (c &Crc32) checksum(b []u8) u32 {
 	return c.sum32(b)
 }
 
-// pass the polynomial to use
+// new creates a `Crc32` polynomial.
 pub fn new(poly int) &Crc32 {
 	mut c := &Crc32{}
 	c.generate_table(poly)
 	return c
 }
 
-// calculate crc32 using ieee
+// sum calculates the CRC-32 checksum of `b` by using the IEEE polynomial.
 pub fn sum(b []u8) u32 {
 	c := new(int(crc32.ieee))
 	return c.sum32(b)
diff --git a/vlib/hash/wyhash.c.v b/vlib/hash/wyhash.c.v
index b8c3cb560b..871c5dbe42 100644
--- a/vlib/hash/wyhash.c.v
+++ b/vlib/hash/wyhash.c.v
@@ -6,21 +6,25 @@ fn C.wyhash(&u8, u64, u64, &u64) u64
 
 fn C.wyhash64(u64, u64) u64
 
+// wyhash_c returns a hash given a byte string `key`, its `len`, and a `seed`.
 [inline]
 pub fn wyhash_c(key &u8, len u64, seed u64) u64 {
 	return C.wyhash(key, len, seed, &u64(C._wyp))
 }
 
+// wyhash64_c returns a hash given two u64 values `a` and `b`.
 [inline]
 pub fn wyhash64_c(a u64, b u64) u64 {
 	return C.wyhash64(a, b)
 }
 
+// sum64_string returns a hash given a V string `key` and a `seed`.
 [inline]
 pub fn sum64_string(key string, seed u64) u64 {
 	return wyhash_c(key.str, u64(key.len), seed)
 }
 
+// sum64 returns a hash given a byte array `key` and a `seed`.
 [inline]
 pub fn sum64(key []u8, seed u64) u64 {
 	return wyhash_c(&u8(key.data), u64(key.len), seed)
diff --git a/vlib/hash/wyhash.v b/vlib/hash/wyhash.v
index 61e5c610a9..20190a634a 100644
--- a/vlib/hash/wyhash.v
+++ b/vlib/hash/wyhash.v
@@ -28,6 +28,7 @@ fn wyrotr(v u64, k u32) u64 {
 	return (v >> k) | (v << (64 - k))
 }
 
+// wymum returns a hash by performing multiply and mix on `a` and `b`.
 [inline]
 pub fn wymum(a u64, b u64) u64 {
 	/*