add function docs to parts of the library

6 files changed, 457 insertions, 0 deletions

diff --git a/include/aesni/all.h b/include/aesni/all.h
index 4653eca..6f00fb7 100644
--- a/include/aesni/all.h
+++ b/include/aesni/all.h
@@ -4,10 +4,16 @@
  * \date 2015
  * \copyright This file is licensed under the terms of the MIT License.
  *            See LICENSE.txt for details.
+ * \brief Include this file to use libaesni.
+ *        Includes all of the other libaesni's header files.
  */
 
 #pragma once
 
+/**
+ * \defgroup aesni AesNI
+ */
+
 #include "block.h"
 #include "buffer.h"
 #include "data.h"
diff --git a/include/aesni/block.h b/include/aesni/block.h
index 0909744..37dfa65 100644
--- a/include/aesni/block.h
+++ b/include/aesni/block.h
@@ -4,10 +4,44 @@
  * \date 2015
  * \copyright This file is licensed under the terms of the MIT License.
  *            See LICENSE.txt for details.
+ * \brief Declares 128-bit block encryption/decryption functions.
  */
 
 #pragma once
 
+/**
+ * \defgroup aesni_block_api Block API
+ * \brief 128-bit block encryption/decryption functions.
+ * \ingroup aesni
+ * \{
+ *
+ * For each of AES-128/192/256, two functions are defined:
+ *
+ * * a key schedule "expansion" function to prepare for encryption,
+ * * a key schedule "reversion" function to prepare for decryption.
+ *
+ * The functions, respectively, are:
+ *
+ * * `aesni_expand_key_scheduleNNN`,
+ * * `aesni_reverse_key_scheduleNNN`,
+ *
+ * where `NNN` is either `128`, `192` or `256`.
+ *
+ * For each of AES-128/192/256 and modes of operation ECB, CBC, CFB, OFB, and
+ * CTR, two functions are defined:
+ *
+ * * a 128-bit block encryption function,
+ * * a 128-bit block decryption function.
+ *
+ * The functions, respectively, are:
+ *
+ * * `aesni_encrypt_block_XXXNNN`,
+ * * `aesni_decrypt_block_XXXNNN`,
+ *
+ * where `XXX` is either `ecb`, `cbc`, `cfb`, `ofb` or `ctr`, and `NNN` is
+ * either `128`, `192` or `256`.
+ */
+
 #include "data.h"
 #include "raw.h"
 
@@ -18,6 +52,12 @@ extern "C"
 {
 #endif
 
+/**
+ * Expands a key schedule for AES-128 encryption.
+ *
+ * \param[in] key The AES-128 key.
+ * \param[out] key_schedule The AES-128 encryption key schedule. Must not be `NULL`.
+ */
 static __inline void __fastcall aesni_expand_key_schedule128(
     AesNI_Block128 key,
     AesNI_KeySchedule128* key_schedule)
@@ -27,6 +67,12 @@ static __inline void __fastcall aesni_expand_key_schedule128(
     aesni_raw_expand_key_schedule128(key, key_schedule);
 }
 
+/**
+ * "Reverses" a key schedule for AES-128 "equivalent inverse cipher" decryption.
+ *
+ * \param[in] key_schedule The AES-128 encryption key schedule. Must not be `NULL`.
+ * \param[out] inverted_schedule The AES-128 decryption key schedule. Must not be `NULL`.
+ */
 static __inline void __fastcall aesni_invert_key_schedule128(
     AesNI_KeySchedule128* key_schedule,
     AesNI_KeySchedule128* inverted_schedule)
@@ -37,6 +83,13 @@ static __inline void __fastcall aesni_invert_key_schedule128(
     aesni_raw_invert_key_schedule128(key_schedule, inverted_schedule);
 }
 
+/**
+ * Encrypts a 128-bit block using AES-128 in ECB mode of operation.
+ *
+ * \param[in] plain The plaintext to be encrypted.
+ * \param[in] key_schedule The AES-128 encryption schedule. Must not be `NULL`.
+ * \return The encrypted 128-bit ciphertext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ecb128(
     AesNI_Block128 plain,
     AesNI_KeySchedule128* key_schedule)
@@ -46,6 +99,13 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ecb128(
     return aesni_raw_encrypt_block128(plain, key_schedule);
 }
 
+/**
+ * Decrypts a 128-bit block using AES-128 in ECB mode of operation.
+ *
+ * \param[in] cipher The ciphertext to be decrypted.
+ * \param[in] inverted_schedule The AES-128 decryption ("reversed") key schedule. Must not be `NULL`.
+ * \return The decrypted 128-bit plaintext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ecb128(
     AesNI_Block128 cipher,
     AesNI_KeySchedule128* inverted_schedule)
@@ -55,6 +115,15 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ecb128(
     return aesni_raw_decrypt_block128(cipher, inverted_schedule);
 }
 
+/**
+ * Encrypts a 128-bit block using AES-128 in CBC mode of operation.
+ *
+ * \param[in] plain The plaintext to be encrypted.
+ * \param[in] key_schedule The AES-128 encryption key schedule. Must not be `NULL`.
+ * \param[in] init_vector The CBC initialization vector.
+ * \param[out] next_init_vector The next CBC initialization vector to be used as the initialization vector for the next call. Must not be `NULL`.
+ * \return The encrypted 128-bit ciphertext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cbc128(
     AesNI_Block128 plain,
     AesNI_KeySchedule128* key_schedule,
@@ -69,6 +138,15 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cbc128(
     return cipher;
 }
 
+/**
+ * Decrypts a 128-bit block using AES-128 in CBC mode of operation.
+ *
+ * \param[in] cipher The ciphertext to be decrypted.
+ * \param[in] inverted_schedule The AES-128 decryption (reversed) key schedule. Must not be `NULL`.
+ * \param[in] init_vector The CBC initialization vector.
+ * \param[out] next_init_vector The next CBC initialization vector to be used as the initialization vector for the next call. Must not be `NULL`.
+ * \return The decrypted 128-bit plaintext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cbc128(
     AesNI_Block128 cipher,
     AesNI_KeySchedule128* inverted_schedule,
@@ -83,6 +161,15 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cbc128(
     return plain;
 }
 
+/**
+ * Encrypts a 128-bit block using AES-128 in CFB mode of operation.
+ *
+ * \param[in] plain The plaintext to be encrypted.
+ * \param[in] key_schedule The AES-128 encryption schedule. Must not be `NULL`.
+ * \param[in] init_vector The CFB initialization vector.
+ * \param[out] next_init_vector The next CFB initialization vector to be used as the initialization vector for the next call. Must not be `NULL`.
+ * \return The encrypted 128-bit ciphertext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cfb128(
     AesNI_Block128 plain,
     AesNI_KeySchedule128* key_schedule,
@@ -97,6 +184,15 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cfb128(
     return cipher;
 }
 
+/**
+ * Decrypts a 128-bit block using AES-128 in CFB mode of operation.
+ *
+ * \param[in] cipher The ciphertext to be decrypted.
+ * \param[in] key_schedule The AES-128 **encryption** key schedule. Must not be `NULL`.
+ * \param[in] init_vector The CFB initialization vector.
+ * \param[out] next_init_vector The next CFB initialization vector to be used as the initialization vector for the next call. Must not be `NULL`.
+ * \return The decrypted 128-bit plaintext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cfb128(
     AesNI_Block128 cipher,
     AesNI_KeySchedule128* key_schedule,
@@ -111,6 +207,15 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cfb128(
     return plain;
 }
 
+/**
+ * Encrypts a 128-bit block using AES-128 in OFB mode of operation.
+ *
+ * \param[in] plain The plaintext to be encrypted.
+ * \param[in] key_schedule The AES-128 encryption schedule. Must not be `NULL`.
+ * \param[in] init_vector The OFB initialization vector.
+ * \param[out] next_init_vector The next OFB initialization vector to be used as the initialization vector for the next call. Must not be `NULL`.
+ * \return The encrypted 128-bit ciphertext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ofb128(
     AesNI_Block128 plain,
     AesNI_KeySchedule128* key_schedule,
@@ -125,6 +230,15 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ofb128(
     return _mm_xor_si128(tmp, plain);
 }
 
+/**
+ * Decrypts a 128-bit block using AES-128 in OFB mode of operation.
+ *
+ * \param[in] cipher The ciphertext to be decrypted.
+ * \param[in] key_schedule The AES-128 **encryption** key schedule. Must not be `NULL`.
+ * \param[in] init_vector The OFB initialization vector.
+ * \param[out] next_init_vector The next OFB initialization vector to be used as the initialization vector for the next call. Must not be `NULL`.
+ * \return The decrypted 128-bit plaintext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ofb128(
     AesNI_Block128 cipher,
     AesNI_KeySchedule128* key_schedule,
@@ -139,6 +253,15 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ofb128(
     return _mm_xor_si128(tmp, cipher);
 }
 
+/**
+ * Encrypts a 128-bit block using AES-128 in CTR mode of operation.
+ *
+ * \param[in] plain The plaintext to be encrypted.
+ * \param[in] key_schedule The AES-128 encryption key schedule. Must not be `NULL`.
+ * \param[in] init_vector The CTR initialization vector.
+ * \param[in] counter The counter, typically incremented between consecutive calls.
+ * \return The encrypted 128-bit ciphertext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ctr128(
     AesNI_Block128 plain,
     AesNI_KeySchedule128* key_schedule,
@@ -153,6 +276,15 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ctr128(
     return _mm_xor_si128(plain, aesni_raw_encrypt_block128(init_vector, key_schedule));
 }
 
+/**
+ * Decrypts a 128-bit block using AES-128 in CTR mode of operation.
+ *
+ * \param[in] cipher The ciphertext to be decrypted.
+ * \param[in] key_schedule The AES-128 **encryption** key schedule. Must not be `NULL`.
+ * \param[in] init_vector The CTR initialization vector.
+ * \param[in] counter The counter, typically incremented between consecutive calls.
+ * \return The decrypted 128-bit plaintext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ctr128(
     AesNI_Block128 cipher,
     AesNI_KeySchedule128* key_schedule,
@@ -167,6 +299,12 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ctr128(
     return _mm_xor_si128(cipher, aesni_raw_encrypt_block128(init_vector, key_schedule));
 }
 
+/**
+ * Expands a key schedule for AES-192 encryption.
+ *
+ * \param[in] key The AES-192 key. Must not be `NULL`.
+ * \param[out] key_schedule The AES-192 encryption key schedule. Must not be `NULL`.
+ */
 static __inline void __fastcall aesni_expand_key_schedule192(
     AesNI_Block192* key,
     AesNI_KeySchedule192* key_schedule)
@@ -177,6 +315,12 @@ static __inline void __fastcall aesni_expand_key_schedule192(
     aesni_raw_expand_key_schedule192(key->lo, key->hi, key_schedule);
 }
 
+/**
+ * "Reverses" a key schedule for AES-192 "equivalent inverse cipher" decryption.
+ *
+ * \param[in] key_schedule The AES-192 encryption key schedule. Must not be `NULL`.
+ * \param[out] inverted_schedule The AES-192 decryption key schedule. Must not be `NULL`.
+ */
 static __inline void __fastcall aesni_invert_key_schedule192(
     AesNI_KeySchedule192* key_schedule,
     AesNI_KeySchedule192* inverted_schedule)
@@ -187,6 +331,13 @@ static __inline void __fastcall aesni_invert_key_schedule192(
     aesni_raw_invert_key_schedule192(key_schedule, inverted_schedule);
 }
 
+/**
+ * Encrypts a 128-bit block using AES-192 in ECB mode of operation.
+ *
+ * \param[in] plain The plaintext to be encrypted.
+ * \param[in] key_schedule The AES-192 encryption schedule. Must not be `NULL`.
+ * \return The encrypted 128-bit ciphertext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ecb192(
     AesNI_Block128 plain,
     AesNI_KeySchedule192* key_schedule)
@@ -196,6 +347,13 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ecb192(
     return aesni_raw_encrypt_block192(plain, key_schedule);
 }
 
+/**
+ * Decrypts a 128-bit block using AES-192 in ECB mode of operation.
+ *
+ * \param[in] cipher The ciphertext to be decrypted.
+ * \param[in] inverted_schedule The AES-192 decryption (reversed) key schedule. Must not be `NULL`.
+ * \return The decrypted 128-bit plaintext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ecb192(
     AesNI_Block128 cipher,
     AesNI_KeySchedule192* inverted_schedule)
@@ -205,6 +363,15 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ecb192(
     return aesni_raw_decrypt_block192(cipher, inverted_schedule);
 }
 
+/**
+ * Encrypts a 128-bit block using AES-192 in CBC mode of operation.
+ *
+ * \param[in] plain The plaintext to be encrypted.
+ * \param[in] key_schedule The AES-192 encryption schedule. Must not be `NULL`.
+ * \param[in] init_vector The CBC initialization vector.
+ * \param[out] next_init_vector The next CBC initialization vector to be used as the initialization vector for the next call. Must not be `NULL`.
+ * \return The encrypted 128-bit ciphertext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cbc192(
     AesNI_Block128 plain,
     AesNI_KeySchedule192* key_schedule,
@@ -219,6 +386,15 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cbc192(
     return cipher;
 }
 
+/**
+ * Decrypts a 128-bit block using AES-192 in CBC mode of operation.
+ *
+ * \param[in] cipher The ciphertext to be decrypted.
+ * \param[in] inverted_schedule The AES-192 decryption (reversed) key schedule. Must not be `NULL`.
+ * \param[in] init_vector The CBC initialization vector.
+ * \param[out] next_init_vector The next CBC initialization vector to be used as the initialization vector for the next call. Must not be `NULL`.
+ * \return The decrypted 128-bit plaintext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cbc192(
     AesNI_Block128 cipher,
     AesNI_KeySchedule192* inverted_schedule,
@@ -233,6 +409,15 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cbc192(
     return plain;
 }
 
+/**
+ * Encrypts a 128-bit block using AES-192 in CFB mode of operation.
+ *
+ * \param[in] plain The plaintext to be encrypted.
+ * \param[in] key_schedule The AES-192 encryption schedule. Must not be `NULL`.
+ * \param[in] init_vector The CFB initialization vector.
+ * \param[out] next_init_vector The next CFB initialization vector to be used as the initialization vector for the next call. Must not be `NULL`.
+ * \return The encrypted 128-bit ciphertext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cfb192(
     AesNI_Block128 plain,
     AesNI_KeySchedule192* key_schedule,
@@ -247,6 +432,15 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cfb192(
     return cipher;
 }
 
+/**
+ * Decrypts a 128-bit block using AES-192 in CFB mode of operation.
+ *
+ * \param[in] cipher The ciphertext to be decrypted.
+ * \param[in] key_schedule The AES-192 **encryption** key schedule. Must not be `NULL`.
+ * \param[in] init_vector The CFB initialization vector.
+ * \param[out] next_init_vector The next CFB initialization vector to be used as the initialization vector for the next call. Must not be `NULL`.
+ * \return The decrypted 128-bit plaintext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cfb192(
     AesNI_Block128 cipher,
     AesNI_KeySchedule192* key_schedule,
@@ -261,6 +455,15 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cfb192(
     return plain;
 }
 
+/**
+ * Encrypts a 128-bit block using AES-192 in OFB mode of operation.
+ *
+ * \param[in] plain The plaintext to be encrypted.
+ * \param[in] key_schedule The AES-192 encryption schedule. Must not be `NULL`.
+ * \param[in] init_vector The OFB initialization vector.
+ * \param[out] next_init_vector The next OFB initialization vector to be used as the initialization vector for the next call. Must not be `NULL`.
+ * \return The encrypted 128-bit ciphertext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ofb192(
     AesNI_Block128 plain,
     AesNI_KeySchedule192* key_schedule,
@@ -275,6 +478,15 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ofb192(
     return _mm_xor_si128(tmp, plain);
 }
 
+/**
+ * Decrypts a 128-bit block using AES-192 in OFB mode of operation.
+ *
+ * \param[in] cipher The ciphertext to be decrypted.
+ * \param[in] key_schedule The AES-192 **encryption** key schedule. Must not be `NULL`.
+ * \param[in] init_vector The OFB initialization vector.
+ * \param[out] next_init_vector The next OFB initialization vector to be used as the initialization vector for the next call. Must not be `NULL`.
+ * \return The decrypted 128-bit plaintext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ofb192(
     AesNI_Block128 cipher,
     AesNI_KeySchedule192* key_schedule,
@@ -289,6 +501,15 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ofb192(
     return _mm_xor_si128(tmp, cipher);
 }
 
+/**
+ * Encrypts a 128-bit block using AES-192 in CTR mode of operation.
+ *
+ * \param[in] plain The plaintext to be encrypted.
+ * \param[in] key_schedule The AES-192 encryption key schedule. Must not be `NULL`.
+ * \param[in] init_vector The CTR initialization vector.
+ * \param[in] counter The counter, typically incremented between consecutive calls.
+ * \return The encrypted 128-bit ciphertext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ctr192(
     AesNI_Block128 plain,
     AesNI_KeySchedule192* key_schedule,
@@ -303,6 +524,15 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ctr192(
     return _mm_xor_si128(plain, aesni_raw_encrypt_block192(init_vector, key_schedule));
 }
 
+/**
+ * Decrypts a 128-bit block using AES-192 in CTR mode of operation.
+ *
+ * \param[in] cipher The ciphertext to be decrypted.
+ * \param[in] key_schedule The AES-192 **encryption** key schedule. Must not be `NULL`.
+ * \param[in] init_vector The CTR initialization vector.
+ * \param[in] counter The counter, typically incremented between consecutive calls.
+ * \return The decrypted 128-bit plaintext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ctr192(
     AesNI_Block128 cipher,
     AesNI_KeySchedule192* key_schedule,
@@ -317,6 +547,12 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ctr192(
     return _mm_xor_si128(cipher, aesni_raw_encrypt_block192(init_vector, key_schedule));
 }
 
+/**
+ * Expands a key schedule for AES-256 encryption.
+ *
+ * \param[in] key The AES-256 key. Must not be `NULL`.
+ * \param[out] key_schedule The AES-256 encryption key schedule. Must not be `NULL`.
+ */
 static __inline void __fastcall aesni_expand_key_schedule256(
     AesNI_Block256* key,
     AesNI_KeySchedule256* key_schedule)
@@ -327,6 +563,12 @@ static __inline void __fastcall aesni_expand_key_schedule256(
     aesni_raw_expand_key_schedule256(key->lo, key->hi, key_schedule);
 }
 
+/**
+ * "Reverses" a key schedule for AES-256 "equivalent inverse cipher" decryption.
+ *
+ * \param[in] key_schedule The AES-256 encryption key schedule. Must not be `NULL`.
+ * \param[out] inverted_schedule The AES-256 decryption key schedule. Must not be `NULL`.
+ */
 static __inline void __fastcall aesni_invert_key_schedule256(
     AesNI_KeySchedule256* key_schedule,
     AesNI_KeySchedule256* inverted_schedule)
@@ -337,6 +579,13 @@ static __inline void __fastcall aesni_invert_key_schedule256(
     aesni_raw_invert_key_schedule256(key_schedule, inverted_schedule);
 }
 
+/**
+ * Encrypts a 128-bit block using AES-256 in ECB mode of operation.
+ *
+ * \param[in] plain The plaintext to be encrypted.
+ * \param[in] key_schedule The AES-256 encryption schedule. Must not be `NULL`.
+ * \return The encrypted 128-bit ciphertext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ecb256(
     AesNI_Block128 plain,
     AesNI_KeySchedule256* key_schedule)
@@ -346,6 +595,13 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ecb256(
     return aesni_raw_encrypt_block256(plain, key_schedule);
 }
 
+/**
+ * Decrypts a 128-bit block using AES-256 in ECB mode of operation.
+ *
+ * \param[in] cipher The ciphertext to be decrypted.
+ * \param[in] inverted_schedule The AES-256 decryption (reversed) key schedule. Must not be `NULL`.
+ * \return The decrypted 128-bit plaintext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ecb256(
     AesNI_Block128 cipher,
     AesNI_KeySchedule256* inverted_schedule)
@@ -355,6 +611,15 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ecb256(
     return aesni_raw_decrypt_block256(cipher, inverted_schedule);
 }
 
+/**
+ * Encrypts a 128-bit block using AES-256 in CBC mode of operation.
+ *
+ * \param[in] plain The plaintext to be encrypted.
+ * \param[in] key_schedule The AES-256 encryption schedule. Must not be `NULL`.
+ * \param[in] init_vector The CBC initialization vector.
+ * \param[out] next_init_vector The next CBC initialization vector to be used as the initialization vector for the next call. Must not be `NULL`.
+ * \return The encrypted 128-bit ciphertext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cbc256(
     AesNI_Block128 plain,
     AesNI_KeySchedule256* key_schedule,
@@ -369,6 +634,15 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cbc256(
     return cipher;
 }
 
+/**
+ * Decrypts a 128-bit block using AES-256 in CBC mode of operation.
+ *
+ * \param[in] cipher The ciphertext to be decrypted.
+ * \param[in] inverted_schedule The AES-256 decryption (reversed) key schedule. Must not be `NULL`.
+ * \param[in] init_vector The CBC initialization vector.
+ * \param[out] next_init_vector The next CBC initialization vector to be used as the initialization vector for the next call. Must not be `NULL`.
+ * \return The decrypted 128-bit plaintext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cbc256(
     AesNI_Block128 cipher,
     AesNI_KeySchedule256* inverted_schedule,
@@ -383,6 +657,15 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cbc256(
     return plain;
 }
 
+/**
+ * Encrypts a 128-bit block using AES-256 in CFB mode of operation.
+ *
+ * \param[in] plain The plaintext to be encrypted.
+ * \param[in] key_schedule The AES-256 encryption schedule. Must not be `NULL`.
+ * \param[in] init_vector The CFB initialization vector.
+ * \param[out] next_init_vector The next CFB initialization vector to be used as the initialization vector for the next call. Must not be `NULL`.
+ * \return The encrypted 128-bit ciphertext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cfb256(
     AesNI_Block128 plain,
     AesNI_KeySchedule256* key_schedule,
@@ -397,6 +680,15 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cfb256(
     return cipher;
 }
 
+/**
+ * Decrypts a 128-bit block using AES-256 in CFB mode of operation.
+ *
+ * \param[in] cipher The ciphertext to be decrypted.
+ * \param[in] key_schedule The AES-256 **encryption** key schedule. Must not be `NULL`.
+ * \param[in] init_vector The CFB initialization vector.
+ * \param[out] next_init_vector The next CFB initialization vector to be used as the initialization vector for the next call. Must not be `NULL`.
+ * \return The decrypted 128-bit plaintext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cfb256(
     AesNI_Block128 cipher,
     AesNI_KeySchedule256* key_schedule,
@@ -411,6 +703,15 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cfb256(
     return plain;
 }
 
+/**
+ * Encrypts a 128-bit block using AES-256 in OFB mode of operation.
+ *
+ * \param[in] plain The plaintext to be encrypted.
+ * \param[in] key_schedule The AES-256 encryption schedule. Must not be `NULL`.
+ * \param[in] init_vector The OFB initialization vector.
+ * \param[out] next_init_vector The next OFB initialization vector to be used as the initialization vector for the next call. Must not be `NULL`.
+ * \return The encrypted 128-bit ciphertext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ofb256(
     AesNI_Block128 plain,
     AesNI_KeySchedule256* key_schedule,
@@ -425,6 +726,15 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ofb256(
     return _mm_xor_si128(tmp, plain);
 }
 
+/**
+ * Decrypts a 128-bit block using AES-256 in OFB mode of operation.
+ *
+ * \param[in] cipher The ciphertext to be decrypted.
+ * \param[in] key_schedule The AES-256 **encryption** key schedule. Must not be `NULL`.
+ * \param[in] init_vector The OFB initialization vector.
+ * \param[out] next_init_vector The next OFB initialization vector to be used as the initialization vector for the next call. Must not be `NULL`.
+ * \return The decrypted 128-bit plaintext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ofb256(
     AesNI_Block128 cipher,
     AesNI_KeySchedule256* key_schedule,
@@ -439,6 +749,15 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ofb256(
     return _mm_xor_si128(tmp, cipher);
 }
 
+/**
+ * Encrypts a 128-bit block using AES-256 in CTR mode of operation.
+ *
+ * \param[in] plain The plaintext to be encrypted.
+ * \param[in] key_schedule The AES-256 encryption key schedule. Must not be `NULL`.
+ * \param[in] init_vector The CTR initialization vector.
+ * \param[in] counter The counter, typically incremented between consecutive calls.
+ * \return The encrypted 128-bit ciphertext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ctr256(
     AesNI_Block128 plain,
     AesNI_KeySchedule256* key_schedule,
@@ -453,6 +772,15 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ctr256(
     return _mm_xor_si128(plain, aesni_raw_encrypt_block256(init_vector, key_schedule));
 }
 
+/**
+ * Decrypts a 128-bit block using AES-256 in CTR mode of operation.
+ *
+ * \param[in] cipher The ciphertext to be decrypted.
+ * \param[in] key_schedule The AES-256 **encryption** key schedule. Must not be `NULL`.
+ * \param[in] init_vector The CTR initialization vector.
+ * \param[in] counter The counter, typically incremented between consecutive calls.
+ * \return The decrypted 128-bit plaintext.
+ */
 static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ctr256(
     AesNI_Block128 cipher,
     AesNI_KeySchedule256* key_schedule,
@@ -470,3 +798,7 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ctr256(
 #ifdef __cplusplus
 }
 #endif
+
+/**
+ * \}
+ */
diff --git a/include/aesni/buffer.h b/include/aesni/buffer.h
index 13f19da..6222f4f 100644
--- a/include/aesni/buffer.h
+++ b/include/aesni/buffer.h
@@ -4,6 +4,7 @@
  * \date 2015
  * \copyright This file is licensed under the terms of the MIT License.
  *            See LICENSE.txt for details.
+ * \brief Declares variable-length buffer encryption/decryption functions.
  */
 
 #pragma once
diff --git a/include/aesni/data.h b/include/aesni/data.h
index de03110..4de3c0e 100644
--- a/include/aesni/data.h
+++ b/include/aesni/data.h
@@ -4,6 +4,8 @@
  * \date 2015
  * \copyright This file is licensed under the terms of the MIT License.
  *            See LICENSE.txt for details.
+ * \brief Declares necessary data structures (for blocks, keys, etc.)
+ *        and auxiliary IO functions.
  */
 
 #pragma once
diff --git a/include/aesni/error.h b/include/aesni/error.h
index 47bd0d6..91bf168 100644
--- a/include/aesni/error.h
+++ b/include/aesni/error.h
@@ -4,6 +4,7 @@
  * \date 2015
  * \copyright This file is licensed under the terms of the MIT License.
  *            See LICENSE.txt for details.
+ * \brief Declares error codes, error formatting functions, etc.
  */
 
 #pragma once
diff --git a/include/aesni/raw.h b/include/aesni/raw.h
index 4432231..2a1902e 100644
--- a/include/aesni/raw.h
+++ b/include/aesni/raw.h
@@ -4,10 +4,35 @@
  * \date 2015
  * \copyright This file is licensed under the terms of the MIT License.
  *            See LICENSE.txt for details.
+ * \brief *Don't use.* Declares "raw" 128-bit block encryption/decryption
+ *        functions.
  */
 
 #pragma once
 
+/**
+ * \defgroup aesni_raw_api Raw API
+ * \brief *Don't use.* "Raw" 128-bit block encryption/decryption functions.
+ * \ingroup aesni
+ * \{
+ *
+ * For each of AES-128/192/256, four functions are defined:
+ *
+ * * a key schedule "expansion" function to prepare for encryption,
+ * * a 128-bit block encryption function using the key schedule,
+ * * a key schedule "reversion" function to prepare for decryption,
+ * * a 128-bit block decryption function using the "inverted" key schedule.
+ *
+ * The functions, respectively, are:
+ *
+ * * `aesni_raw_expand_key_scheduleNNN`,
+ * * `aesni_raw_encrypt_blockNNN`,
+ * * `aesni_raw_invert_key_scheduleNNN`,
+ * * `aesni_raw_decrypt_blockNNN`,
+ *
+ * where `NNN` is key length (either `128`, `192` or `256`).
+ */
+
 #include "data.h"
 
 #ifdef __cplusplus
@@ -15,46 +40,132 @@ extern "C"
 {
 #endif
 
+/**
+ * Expands a key schedule for AES-128 encryption.
+ *
+ * \param[in] key The AES-128 key.
+ * \param[out] key_schedule The AES-128 encryption key schedule. Must not be `NULL`.
+ */
 void __fastcall aesni_raw_expand_key_schedule128(
     AesNI_Block128 key,
     AesNI_KeySchedule128* key_schedule);
+
+/**
+ * "Reverses" a key schedule for AES-128 "equivalent inverse cipher" decryption.
+ *
+ * \param[in] key_schedule The AES-128 encryption key schedule. Must not be `NULL`.
+ * \param[out] inverted_schedule The AES-128 decryption key schedule. Must not be `NULL`.
+ */
 void __fastcall aesni_raw_invert_key_schedule128(
     AesNI_KeySchedule128* key_schedule,
     AesNI_KeySchedule128* inverted_schedule);
 
+/**
+ * Encrypts a 128-bit block using AES-128.
+ *
+ * \param[in] plain The plaintext to be encrypted.
+ * \param[in] key_schedule The AES-128 encryption key schedule. Must not be `NULL`.
+ * \return The encrypted 128-bit ciphertext.
+ */
 AesNI_Block128 __fastcall aesni_raw_encrypt_block128(
     AesNI_Block128 plain,
     AesNI_KeySchedule128* key_schedule);
+
+/**
+ * Decrypts a 128-bit block using AES-128.
+ *
+ * \param[in] cipher The ciphertext to be decrypted.
+ * \param[in] inverted_schedule The AES-128 decryption ("reversed") key schedule. Must not be `NULL`.
+ * \return The decrypted 128-bit plaintext.
+ */
 AesNI_Block128 __fastcall aesni_raw_decrypt_block128(
     AesNI_Block128 cipher,
     AesNI_KeySchedule128* inverted_schedule);
 
+/**
+ * Expands a key schedule for AES-192 encryption.
+ *
+ * \param[in] key_lo The least significant part of the AES-192 key.
+ * \param[in] key_hi The most significant part of the AES-192 key.
+ * \param[out] key_schedule The AES-192 encryption key schedule. Must not be `NULL`.
+ */
 void __fastcall aesni_raw_expand_key_schedule192(
     AesNI_Block128 key_lo,
     AesNI_Block128 key_hi,
     AesNI_KeySchedule192* key_schedule);
+
+/**
+ * "Reverses" a key schedule for AES-192 "equivalent inverse cipher" decryption.
+ *
+ * \param[in] key_schedule The AES-192 encryption key schedule. Must not be `NULL`.
+ * \param[out] inverted_schedule The AES-192 decryption key schedule. Must not be `NULL`.
+ */
 void __fastcall aesni_raw_invert_key_schedule192(
     AesNI_KeySchedule192* key_schedule,
     AesNI_KeySchedule192* inverted_schedule);
 
+/**
+ * Encrypts a 128-bit block using AES-192.
+ *
+ * \param[in] plain The plaintext to be encrypted.
+ * \param[in] key_schedule The AES-192 encryption key schedule. Must not be `NULL`.
+ * \return The encrypted 128-bit ciphertext.
+ */
 AesNI_Block128 __fastcall aesni_raw_encrypt_block192(
     AesNI_Block128 plain,
     AesNI_KeySchedule192* key_schedule);
+
+/**
+ * Decrypts a 128-bit block using AES-192.
+ *
+ * \param[in] cipher The ciphertext to be decrypted.
+ * \param[in] inverted_schedule The AES-192 decryption ("reversed") key schedule. Must not be `NULL`.
+ * \return The decrypted 128-bit plaintext.
+ */
 AesNI_Block128 __fastcall aesni_raw_decrypt_block192(
     AesNI_Block128 cipher,
     AesNI_KeySchedule192* inverted_schedule);
 
+/**
+ * Expands a key schedule for AES-256 encryption.
+ *
+ * \param[in] key_lo The least significant part of the AES-256 key.
+ * \param[in] key_hi The most significant part of the AES-256 key.
+ * \param[out] key_schedule The AES-256 encryption key schedule. Must not be `NULL`.
+ */
 void __fastcall aesni_raw_expand_key_schedule256(
     AesNI_Block128 key_lo,
     AesNI_Block128 key_hi,
     AesNI_KeySchedule256* key_schedule);
+
+/**
+ * "Reverses" a key schedule for AES-256 "equivalent inverse cipher" decryption.
+ *
+ * \param[in] key_schedule The AES-256 encryption key schedule. Must not be `NULL`.
+ * \param[out] inverted_schedule The AES-256 decryption key schedule. Must not be `NULL`.
+ */
 void __fastcall aesni_raw_invert_key_schedule256(
     AesNI_KeySchedule256* key_schedule,
     AesNI_KeySchedule256* inverted_schedule);
 
+/**
+ * Encrypts a 128-bit block using AES-256.
+ *
+ * \param[in] plain The plaintext to be encrypted.
+ * \param[in] key_schedule The AES-256 encryption key schedule. Must not be `NULL`.
+ * \return The encrypted 128-bit ciphertext.
+ */
 AesNI_Block128 __fastcall aesni_raw_encrypt_block256(
     AesNI_Block128 plain,
     AesNI_KeySchedule256* key_schedule);
+
+/**
+ * Decrypts a 128-bit block using AES-256.
+ *
+ * \param[in] cipher The ciphertext to be decrypted.
+ * \param[in] inverted_schedule The AES-256 decryption ("reversed") key schedule. Must not be `NULL`.
+ * \return The decrypted 128-bit plaintext.
+ */
 AesNI_Block128 __fastcall aesni_raw_decrypt_block256(
     AesNI_Block128 cipher,
     AesNI_KeySchedule256* inverted_schedule);
@@ -62,3 +173,7 @@ AesNI_Block128 __fastcall aesni_raw_decrypt_block256(
 #ifdef __cplusplus
 }
 #endif
+
+/**
+ * \}
+ */