update the docs

3 files changed, 214 insertions, 53 deletions

diff --git a/include/aesni/block.h b/include/aesni/block.h
index 37dfa65..a2a4b1b 100644
--- a/include/aesni/block.h
+++ b/include/aesni/block.h
@@ -53,7 +53,12 @@ extern "C"
 #endif
 
 /**
- * Expands a key schedule for AES-128 encryption.
+ * \defgroup aesni_block_api_aes128 AES-128
+ * \{
+ */
+
+/**
+ * \brief 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`.
@@ -68,7 +73,7 @@ static __inline void __fastcall aesni_expand_key_schedule128(
 }
 
 /**
- * "Reverses" a key schedule for AES-128 "equivalent inverse cipher" decryption.
+ * \brief "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`.
@@ -84,7 +89,7 @@ static __inline void __fastcall aesni_invert_key_schedule128(
 }
 
 /**
- * Encrypts a 128-bit block using AES-128 in ECB mode of operation.
+ * \brief 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`.
@@ -100,7 +105,7 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ecb128(
 }
 
 /**
- * Decrypts a 128-bit block using AES-128 in ECB mode of operation.
+ * \brief 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`.
@@ -116,7 +121,7 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ecb128(
 }
 
 /**
- * Encrypts a 128-bit block using AES-128 in CBC mode of operation.
+ * \brief 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`.
@@ -139,7 +144,7 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cbc128(
 }
 
 /**
- * Decrypts a 128-bit block using AES-128 in CBC mode of operation.
+ * \brief 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`.
@@ -162,7 +167,7 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cbc128(
 }
 
 /**
- * Encrypts a 128-bit block using AES-128 in CFB mode of operation.
+ * \brief 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`.
@@ -185,7 +190,7 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cfb128(
 }
 
 /**
- * Decrypts a 128-bit block using AES-128 in CFB mode of operation.
+ * \brief 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`.
@@ -208,7 +213,7 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cfb128(
 }
 
 /**
- * Encrypts a 128-bit block using AES-128 in OFB mode of operation.
+ * \brief 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`.
@@ -231,7 +236,7 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ofb128(
 }
 
 /**
- * Decrypts a 128-bit block using AES-128 in OFB mode of operation.
+ * \brief 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`.
@@ -254,7 +259,7 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ofb128(
 }
 
 /**
- * Encrypts a 128-bit block using AES-128 in CTR mode of operation.
+ * \brief 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`.
@@ -277,7 +282,7 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ctr128(
 }
 
 /**
- * Decrypts a 128-bit block using AES-128 in CTR mode of operation.
+ * \brief 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`.
@@ -300,7 +305,14 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ctr128(
 }
 
 /**
- * Expands a key schedule for AES-192 encryption.
+ * \}
+ *
+ * \defgroup aesni_block_api_aes192 AES-192
+ * \{
+ */
+
+/**
+ * \brief 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`.
@@ -316,7 +328,7 @@ static __inline void __fastcall aesni_expand_key_schedule192(
 }
 
 /**
- * "Reverses" a key schedule for AES-192 "equivalent inverse cipher" decryption.
+ * \brief "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`.
@@ -332,7 +344,7 @@ static __inline void __fastcall aesni_invert_key_schedule192(
 }
 
 /**
- * Encrypts a 128-bit block using AES-192 in ECB mode of operation.
+ * \brief 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`.
@@ -348,7 +360,7 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ecb192(
 }
 
 /**
- * Decrypts a 128-bit block using AES-192 in ECB mode of operation.
+ * \brief 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`.
@@ -364,7 +376,7 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ecb192(
 }
 
 /**
- * Encrypts a 128-bit block using AES-192 in CBC mode of operation.
+ * \brief 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`.
@@ -387,7 +399,7 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cbc192(
 }
 
 /**
- * Decrypts a 128-bit block using AES-192 in CBC mode of operation.
+ * \brief 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`.
@@ -410,7 +422,7 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cbc192(
 }
 
 /**
- * Encrypts a 128-bit block using AES-192 in CFB mode of operation.
+ * \brief 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`.
@@ -433,7 +445,7 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cfb192(
 }
 
 /**
- * Decrypts a 128-bit block using AES-192 in CFB mode of operation.
+ * \brief 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`.
@@ -456,7 +468,7 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cfb192(
 }
 
 /**
- * Encrypts a 128-bit block using AES-192 in OFB mode of operation.
+ * \brief 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`.
@@ -479,7 +491,7 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ofb192(
 }
 
 /**
- * Decrypts a 128-bit block using AES-192 in OFB mode of operation.
+ * \brief 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`.
@@ -502,7 +514,7 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ofb192(
 }
 
 /**
- * Encrypts a 128-bit block using AES-192 in CTR mode of operation.
+ * \brief 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`.
@@ -525,7 +537,7 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ctr192(
 }
 
 /**
- * Decrypts a 128-bit block using AES-192 in CTR mode of operation.
+ * \brief 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`.
@@ -548,7 +560,14 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ctr192(
 }
 
 /**
- * Expands a key schedule for AES-256 encryption.
+ * \}
+ *
+ * \defgroup aesni_block_api_aes256 AES-256
+ * \{
+ */
+
+/**
+ * \brief 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`.
@@ -564,7 +583,7 @@ static __inline void __fastcall aesni_expand_key_schedule256(
 }
 
 /**
- * "Reverses" a key schedule for AES-256 "equivalent inverse cipher" decryption.
+ * \brief "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`.
@@ -580,7 +599,7 @@ static __inline void __fastcall aesni_invert_key_schedule256(
 }
 
 /**
- * Encrypts a 128-bit block using AES-256 in ECB mode of operation.
+ * \brief 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`.
@@ -596,7 +615,7 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ecb256(
 }
 
 /**
- * Decrypts a 128-bit block using AES-256 in ECB mode of operation.
+ * \brief 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`.
@@ -612,7 +631,7 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ecb256(
 }
 
 /**
- * Encrypts a 128-bit block using AES-256 in CBC mode of operation.
+ * \brief 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`.
@@ -635,7 +654,7 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cbc256(
 }
 
 /**
- * Decrypts a 128-bit block using AES-256 in CBC mode of operation.
+ * \brief 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`.
@@ -658,7 +677,7 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cbc256(
 }
 
 /**
- * Encrypts a 128-bit block using AES-256 in CFB mode of operation.
+ * \brief 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`.
@@ -681,7 +700,7 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cfb256(
 }
 
 /**
- * Decrypts a 128-bit block using AES-256 in CFB mode of operation.
+ * \brief 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`.
@@ -704,7 +723,7 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cfb256(
 }
 
 /**
- * Encrypts a 128-bit block using AES-256 in OFB mode of operation.
+ * \brief 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`.
@@ -727,7 +746,7 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ofb256(
 }
 
 /**
- * Decrypts a 128-bit block using AES-256 in OFB mode of operation.
+ * \brief 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`.
@@ -750,7 +769,7 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ofb256(
 }
 
 /**
- * Encrypts a 128-bit block using AES-256 in CTR mode of operation.
+ * \brief 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`.
@@ -773,7 +792,7 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ctr256(
 }
 
 /**
- * Decrypts a 128-bit block using AES-256 in CTR mode of operation.
+ * \brief 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`.
@@ -795,6 +814,10 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ctr256(
     return _mm_xor_si128(cipher, aesni_raw_encrypt_block256(init_vector, key_schedule));
 }
 
+/**
+ * \}
+ */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/include/aesni/data.h b/include/aesni/data.h
index 4de3c0e..e7cf4ef 100644
--- a/include/aesni/data.h
+++ b/include/aesni/data.h
@@ -5,11 +5,18 @@
  * \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.
+ *        and auxiliary I/O functions.
  */
 
 #pragma once
 
+/**
+ * \defgroup aesni_data Data
+ * \brief Data structures and I/O functions
+ * \ingroup aesni
+ * \{
+ */
+
 #include <emmintrin.h>
 #include <tmmintrin.h>
 
@@ -18,31 +25,108 @@ extern "C"
 {
 #endif
 
+/**
+ * \brief Represents a 128-bit block.
+ */
 typedef __m128i AesNI_Block128;
 
+/**
+ * \brief Loads a 128-bit block from a memory location.
+ *
+ * \param[in] src The pointer to a memory location. Must not be `NULL`.
+ * \return The loaded 128-bit block.
+ */
 static __inline AesNI_Block128 aesni_load_block128(const void* src)
 {
     return _mm_loadu_si128((AesNI_Block128*) src);
 }
 
+/**
+ * \brief Loads a 128-bit block from a 16-byte aligned memory location.
+ *
+ * \param[in] src The pointer to a 16-byte aligned memory location. Must not be `NULL`.
+ * \return The loaded 128-bit block.
+ */
+static __inline AesNI_Block128 aseni_load_block128_aligned(const void* src)
+{
+    return _mm_load_si128((AesNI_Block128*) src);
+}
+
+/**
+ * \brief Stores a 128-bit block in a memory location.
+ *
+ * \param[out] dest The pointer to a memory location. Must not be `NULL`.
+ * \param[in] block The block to be stored.
+ */
 static __inline void __fastcall aesni_store_block128(
     void* dest, AesNI_Block128 block)
 {
     _mm_storeu_si128((AesNI_Block128*) dest, block);
 }
 
+/**
+ * \brief Stores a 128-bit block in a 16-byte aligned memory location.
+ *
+ * \param[out] dest The pointer to a 16-byte aligned memory location. Must not be `NULL`.
+ * \param[in] block The block to be stored.
+ */
+static __inline void __fastcall aesni_store_block128_aligned(
+    void* dest, AesNI_Block128 block)
+{
+    _mm_store_si128((AesNI_Block128*) dest, block);
+}
+
+/**
+ * \brief Builds a 128-bit block from four 4-byte values.
+ *
+ * Builds a 128-bit block like this:
+ *
+ * * dest[127:96] = hi3
+ * * dest[95:64] = hi2
+ * * dest[63:32] = lo1
+ * * dest[31:0] = lo0
+ *
+ * \param[in] hi3 The most significant 4-byte value.
+ * \param[in] hi2 The more significant 4-byte value.
+ * \param[in] lo1 The less significant 4-byte value.
+ * \param[in] lo0 The least significant 4-byte value.
+ * \return The built 128-bit block.
+ */
 static __inline AesNI_Block128 __fastcall aesni_make_block128(int hi3, int hi2, int lo1, int lo0)
 {
     return _mm_set_epi32(hi3, hi2, lo1, lo0);
 }
 
+/**
+ * \brief Represents a 192-bit block.
+ */
 typedef struct
 {
-    AesNI_Block128 hi;
-    AesNI_Block128 lo;
+    AesNI_Block128 hi; ///< The most significant 64 bits. The higher 64 bits are ignored.
+    AesNI_Block128 lo; ///< The least significant 128 bits.
 }
 AesNI_Block192;
 
+/**
+ * \brief Builds a 192-bit block from six 4-byte values.
+ *
+ * Builds a 192-bit block like this:
+ *
+ * * dest[191:160] = hi5
+ * * dest[159:128] = hi4
+ * * dest[127:96] = lo3
+ * * dest[95:64] = lo2
+ * * dest[63:32] = lo1
+ * * dest[31:0] = lo0
+ *
+ * \param[in] hi5 The most significant 4-byte value (bits 160--191).
+ * \param[in] hi4 The more significant 4-byte value (bits 128--159).
+ * \param[in] lo3 The 4-byte value to be stored in bits 96--127.
+ * \param[in] lo2 The 4-byte value to be stored in bits 64--95.
+ * \param[in] lo1 The less significant 4-byte value (bits 32--63).
+ * \param[in] lo0 The least significant 4-byte value (bits 0--31).
+ * \return The built 192-bit block.
+ */
 static __inline AesNI_Block192 __fastcall aesni_make_block192(int hi5, int hi4, int lo3, int lo2, int lo1, int lo0)
 {
     AesNI_Block192 result;
@@ -51,13 +135,40 @@ static __inline AesNI_Block192 __fastcall aesni_make_block192(int hi5, int hi4,
     return result;
 }
 
+/**
+ * \brief Represents a 256-bit block.
+ */
 typedef struct
 {
-    AesNI_Block128 hi;
-    AesNI_Block128 lo;
+    AesNI_Block128 hi; ///< The most significant 128 bits.
+    AesNI_Block128 lo; ///< The least significant 128 bits.
 }
 AesNI_Block256;
 
+/**
+ * \brief Builds a 256-bit block from eight 4-byte values.
+ *
+ * Builds a 256-bit block like this:
+ *
+ * * dest[255:224] = hi7
+ * * dest[223:192] = hi6
+ * * dest[191:160] = hi5
+ * * dest[159:128] = hi4
+ * * dest[127:96] = lo3
+ * * dest[95:64] = lo2
+ * * dest[63:32] = lo1
+ * * dest[31:0] = lo0
+ *
+ * \param[in] hi7 The 4-byte value to be stored in bits 224--255.
+ * \param[in] hi6 The 4-byte value to be stored in bits 192--223.
+ * \param[in] hi5 The 4-byte value to be stored in bits 160--191.
+ * \param[in] hi4 The 4-byte value to be stored in bits 128--159.
+ * \param[in] lo3 The 4-byte value to be stored in bits 96--127.
+ * \param[in] lo2 The 4-byte value to be stored in bits 64--95.
+ * \param[in] lo1 The 4-byte value to be stored in bits 32--63.
+ * \param[in] lo0 The 4-byte value to be stored in bits 0--31.
+ * \return The built 256-bit block.
+ */
 static __inline AesNI_Block256 __fastcall aesni_make_block256(int hi7, int hi6, int hi5, int hi4, int lo3, int lo2, int lo1, int lo0)
 {
     AesNI_Block256 result;
@@ -162,3 +273,7 @@ int aesni_parse_block256_be(AesNI_Block256*, const char*);
 #ifdef __cplusplus
 }
 #endif
+
+/**
+ * \}
+ */
diff --git a/include/aesni/raw.h b/include/aesni/raw.h
index 2a1902e..4b35266 100644
--- a/include/aesni/raw.h
+++ b/include/aesni/raw.h
@@ -41,7 +41,12 @@ extern "C"
 #endif
 
 /**
- * Expands a key schedule for AES-128 encryption.
+ * \defgroup aesni_raw_api_aes128 AES-128
+ * \{
+ */
+
+/**
+ * \brief 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`.
@@ -51,7 +56,7 @@ void __fastcall aesni_raw_expand_key_schedule128(
     AesNI_KeySchedule128* key_schedule);
 
 /**
- * "Reverses" a key schedule for AES-128 "equivalent inverse cipher" decryption.
+ * \brief "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`.
@@ -61,7 +66,7 @@ void __fastcall aesni_raw_invert_key_schedule128(
     AesNI_KeySchedule128* inverted_schedule);
 
 /**
- * Encrypts a 128-bit block using AES-128.
+ * \brief 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`.
@@ -72,7 +77,7 @@ AesNI_Block128 __fastcall aesni_raw_encrypt_block128(
     AesNI_KeySchedule128* key_schedule);
 
 /**
- * Decrypts a 128-bit block using AES-128.
+ * \brief 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`.
@@ -83,7 +88,14 @@ AesNI_Block128 __fastcall aesni_raw_decrypt_block128(
     AesNI_KeySchedule128* inverted_schedule);
 
 /**
- * Expands a key schedule for AES-192 encryption.
+ * \}
+ *
+ * \defgroup aesni_raw_api_aes192 AES-192
+ * \{
+ */
+
+/**
+ * \brief 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.
@@ -95,7 +107,7 @@ void __fastcall aesni_raw_expand_key_schedule192(
     AesNI_KeySchedule192* key_schedule);
 
 /**
- * "Reverses" a key schedule for AES-192 "equivalent inverse cipher" decryption.
+ * \brief "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`.
@@ -105,7 +117,7 @@ void __fastcall aesni_raw_invert_key_schedule192(
     AesNI_KeySchedule192* inverted_schedule);
 
 /**
- * Encrypts a 128-bit block using AES-192.
+ * \brief 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`.
@@ -116,7 +128,7 @@ AesNI_Block128 __fastcall aesni_raw_encrypt_block192(
     AesNI_KeySchedule192* key_schedule);
 
 /**
- * Decrypts a 128-bit block using AES-192.
+ * \brief 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`.
@@ -127,7 +139,14 @@ AesNI_Block128 __fastcall aesni_raw_decrypt_block192(
     AesNI_KeySchedule192* inverted_schedule);
 
 /**
- * Expands a key schedule for AES-256 encryption.
+ * \}
+ *
+ * \defgroup aesni_raw_api_aes256 AES-256
+ * \{
+ */
+
+/**
+ * \brief 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.
@@ -139,7 +158,7 @@ void __fastcall aesni_raw_expand_key_schedule256(
     AesNI_KeySchedule256* key_schedule);
 
 /**
- * "Reverses" a key schedule for AES-256 "equivalent inverse cipher" decryption.
+ * \brief "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`.
@@ -149,7 +168,7 @@ void __fastcall aesni_raw_invert_key_schedule256(
     AesNI_KeySchedule256* inverted_schedule);
 
 /**
- * Encrypts a 128-bit block using AES-256.
+ * \brief 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`.
@@ -160,7 +179,7 @@ AesNI_Block128 __fastcall aesni_raw_encrypt_block256(
     AesNI_KeySchedule256* key_schedule);
 
 /**
- * Decrypts a 128-bit block using AES-256.
+ * \brief 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`.
@@ -170,6 +189,10 @@ AesNI_Block128 __fastcall aesni_raw_decrypt_block256(
     AesNI_Block128 cipher,
     AesNI_KeySchedule256* inverted_schedule);
 
+/**
+ * \}
+ */
+
 #ifdef __cplusplus
 }
 #endif