crypto: add missing documentation to all pub functions (#8251)

vlib/crypto/aes/aes.v

@@ -12,14 +12,14 @@ pub const (
 	block_size = 16
 )
 
-// A cipher is an instance of AES encryption using a particular key.
+// AesCipher represents an AES encryption using a particular key.
 struct AesCipher {
 mut:
 	enc []u32
 	dec []u32
 }
 
-// new_cipher creates and returns a new cipher.Block.
+// new_cipher creates and returns a new `AesCipher`.
 // The key argument should be the AES key,
 // either 16, 24, or 32 bytes to select
 // AES-128, AES-192, or AES-256.
@@ -38,10 +38,13 @@ pub fn new_cipher(key []byte) AesCipher {
 	return new_cipher_generic(key)
 }
 
+// block_size returns the block size of the checksum in bytes.
 pub fn (c &AesCipher) block_size() int {
 	return block_size
 }
 
+// encrypt encrypts the blocks in `src` to `dst`.
+// Please note: `dst` and `src` are both mutable for performance reasons.
 pub fn (c &AesCipher) encrypt(mut dst []byte, mut src []byte) {
 	if src.len < block_size {
 		panic('crypto.aes: input not full block')
@@ -57,6 +60,8 @@ pub fn (c &AesCipher) encrypt(mut dst []byte, mut src []byte) {
 	encrypt_block_generic(c.enc, mut dst, src)
 }
 
+// decrypt decrypts the blocks in `src` to `dst`.
+// Please note: `dst` and `src` are both mutable for performance reasons.
 pub fn (c &AesCipher) decrypt(mut dst []byte, mut src []byte) {
 	if src.len < block_size {
 		panic('crypto.aes: input not full block')

vlib/crypto/aes/aes_cbc.v

@@ -29,7 +29,7 @@ fn new_aes_cbc(b AesCipher, iv []byte) AesCbc {
 	}
 }
 
-// new_cbc_encrypter returns a BlockMode which encrypts in cipher block chaining
+// new_cbc returns a `AesCbc` which encrypts in cipher block chaining
 // mode, using the given Block. The length of iv must be the same as the
 // Block's block size.
 pub fn new_cbc(b AesCipher, iv []byte) AesCbc {
@@ -39,10 +39,13 @@ pub fn new_cbc(b AesCipher, iv []byte) AesCbc {
 	return new_aes_cbc(b, iv)
 }
 
+// block_size returns the block size of the checksum in bytes.
 pub fn (x &AesCbc) block_size() int {
 	return x.block_size
 }
 
+// encrypt_blocks encrypts the blocks in `src_` to `dst_`.
+// Please note: `dst_` is mutable for performance reasons.
 pub fn (x &AesCbc) encrypt_blocks(mut dst_ []byte, src_ []byte) {
 	unsafe {
 		mut dst := *dst_
@@ -75,6 +78,8 @@ pub fn (x &AesCbc) encrypt_blocks(mut dst_ []byte, src_ []byte) {
 	}
 }
 
+// decrypt_blocks decrypts the blocks in `src` to `dst`.
+// Please note: `dst` is mutable for performance reasons.
 pub fn (mut x AesCbc) decrypt_blocks(mut dst []byte, src []byte) {
 	if src.len % x.block_size != 0 {
 		panic('crypto.cipher: input not full blocks')

vlib/crypto/cipher/xor_generic.v

@@ -18,15 +18,16 @@ pub fn xor_bytes(mut dst []byte, a []byte, b []byte) int {
 	return n
 }
 
-// n needs to be smaller or equal than the length of a and b.
+// safe_xor_bytes XORs the bytes in `a` and `b` into `dst` it does so `n` times.
+// Please note: `n` needs to be smaller or equal than the length of `a` and `b`.
 pub fn safe_xor_bytes(mut dst []byte, a []byte, b []byte, n int) {
 	for i in 0 .. n {
 		dst[i] = a[i] ^ b[i]
 	}
 }
 
-// fast_xor_words XORs multiples of 4 or 8 bytes (depending on architecture.)
-// The slice arguments a and b are assumed to be of equal length.
+// xor_words XORs multiples of 4 or 8 bytes (depending on architecture.)
+// The slice arguments `a` and `b` are assumed to be of equal length.
 pub fn xor_words(mut dst []byte, a []byte, b []byte) {
 	safe_xor_bytes(mut dst, a, b, b.len)
 }

vlib/crypto/hmac/hmac.v

@@ -10,7 +10,7 @@ const (
 	npad = []byte{len: 256, init: 0}
 )
 
-// Returns an HMAC byte array, depending on the hash algorithm used
+// new returns a HMAC byte array, depending on the hash algorithm used.
 pub fn new(key []byte, data []byte, hash_func fn (bytes []byte) []byte, blocksize int) []byte {
 	mut b_key := []byte{}
 	if key.len <= blocksize {
@@ -36,7 +36,7 @@ pub fn new(key []byte, data []byte, hash_func fn (bytes []byte) []byte, blocksiz
 	return digest
 }
 
-// equal compares 2 MACs for equality, without leaking timing info
+// equal compares 2 MACs for equality, without leaking timing info.
 // NB: if the lengths of the 2 MACs are different, probably a completely different
 // hash function was used to generate them => no useful timing information.
 pub fn equal(mac1 []byte, mac2 []byte) bool {

vlib/crypto/md5/md5.v

@@ -51,7 +51,8 @@ pub fn new() &Digest {
 	return d
 }
 
-fn (mut d Digest) write(p_ []byte) int {
+// write writes the contents of `p_` to the internal hash representation.
+pub fn (mut d Digest) write(p_ []byte) int {
 	unsafe {
 		mut p := p_
 		nn := p.len
@@ -85,7 +86,8 @@ fn (mut d Digest) write(p_ []byte) int {
 	}
 }
 
-fn (d &Digest) sum(b_in []byte) []byte {
+// sum returns the md5 sum of the bytes in `b_in`.
+pub fn (d &Digest) sum(b_in []byte) []byte {
 	// Make a copy of d so that caller can keep writing and summing.
 	mut d0 := *d
 	hash := d0.checksum()
@@ -96,6 +98,7 @@ fn (d &Digest) sum(b_in []byte) []byte {
 	return b_out
 }
 
+// checksum returns the byte checksum of the `Digest`.
 pub fn (mut d Digest) checksum() []byte {
 	// Append 0x80 to the end of the message and then append zeros
 	// until the length is a multiple of 56 bytes. Finally append
@@ -134,14 +137,18 @@ fn block(mut dig Digest, p []byte) {
 	block_generic(mut dig, p)
 }
 
+// size returns the size of the checksum in bytes.
 pub fn (d &Digest) size() int {
 	return size
 }
 
+// block_size returns the block size of the checksum in bytes.
 pub fn (d &Digest) block_size() int {
 	return block_size
 }
 
+// hexhash returns a hexadecimal MD5 hash sum `string` of `s`.
+// Example: assert md5.hexhash('V') == '5206560a306a2e085a437fd258eb57ce'
 pub fn hexhash(s string) string {
 	return sum(s.bytes()).hex()
 }

vlib/crypto/rand/rand_darwin.c.v

@@ -10,6 +10,7 @@ module rand
 
 fn C.SecRandomCopyBytes() int
 
+// read returns an array of `bytes_needed` random bytes read from the OS.
 pub fn read(bytes_needed int) ?[]byte {
 	mut buffer := malloc(bytes_needed)
 	status := C.SecRandomCopyBytes(0, bytes_needed, buffer)

vlib/crypto/rand/rand_linux.c.v

@@ -8,6 +8,7 @@ const (
 	read_batch_size = 256
 )
 
+// read returns an array of `bytes_needed` random bytes read from the OS.
 pub fn read(bytes_needed int) ?[]byte {
 	mut buffer := &byte(0)
 	unsafe {

vlib/crypto/rand/rand_solaris.c.v

@@ -12,6 +12,7 @@ const (
 	read_batch_size = 256
 )
 
+// read returns an array of `bytes_needed` random bytes read from the OS.
 pub fn read(bytes_needed int) ?[]byte {
 	mut buffer := &byte(0)
 	unsafe {

vlib/crypto/rand/rand_windows.c.v

@@ -13,6 +13,7 @@ const (
 	bcrypt_use_system_preferred_rng = 0x00000002
 )
 
+// read returns an array of `bytes_needed` random bytes read from the OS.
 pub fn read(bytes_needed int) ?[]byte {
 	mut buffer := malloc(bytes_needed)
 	// use bcrypt_use_system_preferred_rng because we passed null as algo

vlib/crypto/sha1/sha1.v

@@ -54,8 +54,9 @@ pub fn new() &Digest {
 	return d
 }
 
+// write writes the contents of `p_` to the internal hash representation.
 [manualfree]
-fn (mut d Digest) write(p_ []byte) int {
+pub fn (mut d Digest) write(p_ []byte) int {
 	nn := p_.len
 	unsafe {
 		mut p := p_
@@ -89,7 +90,8 @@ fn (mut d Digest) write(p_ []byte) int {
 	return nn
 }
 
-fn (d &Digest) sum(b_in []byte) []byte {
+// sum returns a copy of the generated sum of the bytes in `b_in`.
+pub fn (d &Digest) sum(b_in []byte) []byte {
 	// Make a copy of d so that caller can keep writing and summing.
 	mut d0 := *d
 	hash := d0.checksum()
@@ -100,6 +102,7 @@ fn (d &Digest) sum(b_in []byte) []byte {
 	return b_out
 }
 
+// checksum returns the byte checksum of the `Digest`.
 fn (mut d Digest) checksum() []byte {
 	mut len := d.len
 	// Padding.  Add a 1 bit and 0 bits until 56 bytes mod 64.
@@ -123,7 +126,7 @@ fn (mut d Digest) checksum() []byte {
 	return digest
 }
 
-// Sum returns the SHA-1 checksum of the data.
+// sum returns the SHA-1 checksum of the bytes passed in `data`.
 pub fn sum(data []byte) []byte {
 	mut d := new()
 	d.write(data)
@@ -136,14 +139,17 @@ fn block(mut dig Digest, p []byte) {
 	block_generic(mut dig, p)
 }
 
+// size returns the size of the checksum in bytes.
 pub fn (d &Digest) size() int {
 	return size
 }
 
+// block_size returns the block size of the checksum in bytes.
 pub fn (d &Digest) block_size() int {
 	return block_size
 }
 
+// hexhash returns a hexadecimal SHA1 hash sum `string` of `s`.
 pub fn hexhash(s string) string {
 	return sum(s.bytes()).hex()
 }

vlib/crypto/sha256/sha256.v

@@ -89,6 +89,7 @@ pub fn new224() &Digest {
 	return d
 }
 
+// write writes the contents of `p_` to the internal hash representation.
 fn (mut d Digest) write(p_ []byte) int {
 	unsafe {
 		mut p := p_
@@ -171,7 +172,8 @@ fn (mut d Digest) checksum() []byte {
 	return digest
 }
 
-// sum256 returns the SHA256 checksum of the data.
+// sum returns the SHA256 checksum of the bytes in `data`.
+// Example: assert sha256.sum('V'.bytes()).len > 0 == true
 pub fn sum(data []byte) []byte {
 	return sum256(data)
 }
@@ -199,6 +201,7 @@ fn block(mut dig Digest, p []byte) {
 	block_generic(mut dig, p)
 }
 
+// size returns the size of the checksum in bytes.
 pub fn (d &Digest) size() int {
 	if !d.is224 {
 		return size
@@ -206,14 +209,18 @@ pub fn (d &Digest) size() int {
 	return size224
 }
 
+// block_size returns the block size of the checksum in bytes.
 pub fn (d &Digest) block_size() int {
 	return block_size
 }
 
+// hexhash returns a hexadecimal SHA256 hash sum `string` of `s`.
+// Example: assert sha256.hexhash('V') == 'de5a6f78116eca62d7fc5ce159d23ae6b889b365a1739ad2cf36f925a140d0cc'
 pub fn hexhash(s string) string {
 	return sum256(s.bytes()).hex()
 }
 
+// hexhash_224 returns a hexadecimal SHA224 hash sum `string` of `s`.
 pub fn hexhash_224(s string) string {
 	return sum224(s.bytes()).hex()
 }

vlib/crypto/sha512/sha512.v

@@ -60,7 +60,7 @@ const (
 	init7_384 = u64(0x47b5481dbefa4fa4)
 )
 
-// digest represents the partial evaluation of a checksum.
+// Digest represents the partial evaluation of a checksum.
 struct Digest {
 mut:
 	h        []u64
@@ -148,6 +148,7 @@ fn new384() &Digest {
 	return new_digest(.sha384)
 }
 
+// write writes the contents of `p_` to the internal hash representation.
 fn (mut d Digest) write(p_ []byte) int {
 	unsafe {
 		mut p := p_
@@ -271,7 +272,7 @@ pub fn sum512_224(data []byte) []byte {
 	return sum224
 }
 
-// Sum512_256 returns the Sum512/256 checksum of the data.
+// sum512_256 returns the Sum512/256 checksum of the data.
 pub fn sum512_256(data []byte) []byte {
 	mut d := new_digest(.sha512_256)
 	d.write(data)
@@ -287,6 +288,7 @@ fn block(mut dig Digest, p []byte) {
 	block_generic(mut dig, p)
 }
 
+// size returns the size of the checksum in bytes.
 pub fn (d &Digest) size() int {
 	match d.function {
 		.sha512_224 { return size224 }
@@ -296,22 +298,27 @@ pub fn (d &Digest) size() int {
 	}
 }
 
+// block_size returns the block size of the checksum in bytes.
 pub fn (d &Digest) block_size() int {
 	return block_size
 }
 
+// hexhash returns a hexadecimal SHA512 hash sum `string` of `s`.
 pub fn hexhash(s string) string {
 	return sum512(s.bytes()).hex()
 }
 
+// hexhash_384 returns a hexadecimal SHA384 hash sum `string` of `s`.
 pub fn hexhash_384(s string) string {
 	return sum384(s.bytes()).hex()
 }
 
+// hexhash_512_224 returns a hexadecimal SHA512/224 hash sum `string` of `s`.
 pub fn hexhash_512_224(s string) string {
 	return sum512_224(s.bytes()).hex()
 }
 
+// hexhash_512_256 returns a hexadecimal 512/256 hash sum `string` of `s`.
 pub fn hexhash_512_256(s string) string {
 	return sum512_256(s.bytes()).hex()
 }