crypto.blowfish: add doc comments for the public API (#12609)

vlib/crypto/blowfish/block.v

@@ -1,5 +1,6 @@
 module blowfish
 
+// expand_key performs a key expansion on the given Blowfish cipher.
 pub fn expand_key(key []byte, mut bf Blowfish) {
 	mut j := 0
 	for i := 0; i < 18; i++ {
@@ -17,28 +18,29 @@ pub fn expand_key(key []byte, mut bf Blowfish) {
 	mut l := u32(0)
 	mut r := u32(0)
 	for i := 0; i < 18; i += 2 {
-		arr := encrypt_block(l, r, mut bf)
+		arr := setup_tables(l, r, mut bf)
 		bf.p[i], bf.p[i + 1] = arr[0], arr[1]
 	}
 
 	for i := 0; i < 256; i += 2 {
-		arr := encrypt_block(l, r, mut bf)
+		arr := setup_tables(l, r, mut bf)
 		bf.s[0][i], bf.s[0][i + 1] = arr[0], arr[1]
 	}
 	for i := 0; i < 256; i += 2 {
-		arr := encrypt_block(l, r, mut bf)
+		arr := setup_tables(l, r, mut bf)
 		bf.s[1][i], bf.s[1][i + 1] = arr[0], arr[1]
 	}
 	for i := 0; i < 256; i += 2 {
-		arr := encrypt_block(l, r, mut bf)
+		arr := setup_tables(l, r, mut bf)
 		bf.s[2][i], bf.s[2][i + 1] = arr[0], arr[1]
 	}
 	for i := 0; i < 256; i += 2 {
-		arr := encrypt_block(l, r, mut bf)
+		arr := setup_tables(l, r, mut bf)
 		bf.s[3][i], bf.s[3][i + 1] = arr[0], arr[1]
 	}
 }
 
+// expand_key_with_salt using salt to expand the key.
 pub fn expand_key_with_salt(key []byte, salt []byte, mut bf Blowfish) {
 	mut j := 0
 	for i := 0; i < 18; i++ {
@@ -52,37 +54,38 @@ pub fn expand_key_with_salt(key []byte, salt []byte, mut bf Blowfish) {
 	for i := 0; i < 18; i += 2 {
 		l ^= get_next_word(key, &j)
 		r ^= get_next_word(key, &j)
-		arr := encrypt_block(l, r, mut bf)
+		arr := setup_tables(l, r, mut bf)
 		bf.p[i], bf.p[i + 1] = arr[0], arr[1]
 	}
 
 	for i := 0; i < 256; i += 2 {
 		l ^= get_next_word(key, &j)
 		r ^= get_next_word(key, &j)
-		arr := encrypt_block(l, r, mut bf)
+		arr := setup_tables(l, r, mut bf)
 		bf.s[0][i], bf.s[0][i + 1] = arr[0], arr[1]
 	}
 	for i := 0; i < 256; i += 2 {
 		l ^= get_next_word(key, &j)
 		r ^= get_next_word(key, &j)
-		arr := encrypt_block(l, r, mut bf)
+		arr := setup_tables(l, r, mut bf)
 		bf.s[1][i], bf.s[1][i + 1] = arr[0], arr[1]
 	}
 	for i := 0; i < 256; i += 2 {
 		l ^= get_next_word(key, &j)
 		r ^= get_next_word(key, &j)
-		arr := encrypt_block(l, r, mut bf)
+		arr := setup_tables(l, r, mut bf)
 		bf.s[2][i], bf.s[2][i + 1] = arr[0], arr[1]
 	}
 	for i := 0; i < 256; i += 2 {
 		l ^= get_next_word(key, &j)
 		r ^= get_next_word(key, &j)
-		arr := encrypt_block(l, r, mut bf)
+		arr := setup_tables(l, r, mut bf)
 		bf.s[3][i], bf.s[3][i + 1] = arr[0], arr[1]
 	}
 }
 
-fn encrypt_block(l u32, r u32, mut bf Blowfish) []u32 {
+// setup_tables sets up the Blowfish cipher's pi and substitution tables.
+fn setup_tables(l u32, r u32, mut bf Blowfish) []u32 {
 	mut xl := l
 	mut xr := r
 	xl ^= bf.p[0]
@@ -123,6 +126,8 @@ fn encrypt_block(l u32, r u32, mut bf Blowfish) []u32 {
 	return res
 }
 
+// get_next_word returns the next big-endian u32 value from the byte
+// slice at the given position in a circular manner, updating the position.
 fn get_next_word(b []byte, pos &int) u32 {
 	mut w := u32(0)
 	mut j := 0

vlib/crypto/blowfish/blowfish.v

@@ -6,6 +6,8 @@ pub mut:
 	s [4][256]u32
 }
 
+// new_cipher creates and returns a new Blowfish cipher.
+// The key argument should be the Blowfish key, from 1 to 56 bytes.
 pub fn new_cipher(key []byte) ?Blowfish {
 	mut bf := Blowfish{}
 	unsafe { vmemcpy(&bf.p[0], &p[0], int(sizeof(bf.p))) }
@@ -18,6 +20,7 @@ pub fn new_cipher(key []byte) ?Blowfish {
 	return bf
 }
 
+// new_salted_cipher returns a new Blowfish cipher that folds a salt into its key schedule.
 pub fn new_salted_cipher(key []byte, salt []byte) ?Blowfish {
 	if salt.len == 0 {
 		return new_cipher(key)
@@ -32,10 +35,11 @@ pub fn new_salted_cipher(key []byte, salt []byte) ?Blowfish {
 	return bf
 }
 
+// encrypt encrypts the 8-byte buffer src using the key k and stores the result in dst.
 pub fn (mut bf Blowfish) encrypt(mut dst []byte, src []byte) {
 	l := u32(src[0]) << 24 | u32(src[1]) << 16 | u32(src[2]) << 8 | u32(src[3])
 	r := u32(src[4]) << 24 | u32(src[5]) << 16 | u32(src[6]) << 8 | u32(src[7])
-	arr := encrypt_block(l, r, mut bf)
+	arr := setup_tables(l, r, mut bf)
 	dst[0], dst[1], dst[2], dst[3] = byte(arr[0] >> 24), byte(arr[0] >> 16), byte(arr[0] >> 8), byte(arr[0])
 	dst[4], dst[5], dst[6], dst[7] = byte(arr[1] >> 24), byte(arr[1] >> 16), byte(arr[1] >> 8), byte(arr[1])
 }