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')