docs: Use examples first and unify structure of sections.

docs/reference/evercrypt/dh/ec/index.md

@@ -2,12 +2,14 @@
 
 Elliptic-curve Diffie-Hellman key agreement on Curve25519.
 
-## API Reference
+## Available Implementations
 
 ```C
 #include "EverCrypt_Curve25519.h"
 ```
 
+## API Reference
+
 ```{doxygenfunction} EverCrypt_Curve25519_scalarmult
 ```
 

docs/reference/evercrypt/randomness/index.md

@@ -4,12 +4,14 @@
 
 Deterministic Random Bit Generator (DRBG) (NIST, SP 800-90A).
 
-### API Reference
+## Available Implementations
 
 ```C
 #include "EverCrypt_DRBG.h"
 ```
 
+### API Reference
+
 #### Variables
 
 ```{doxygenvariable} EverCrypt_DRBG_reseed_interval

docs/reference/hacl/aead/chacha20poly1305.md

@@ -1,12 +1,7 @@
 # Chacha20-Poly1305
 
 HACL implements the Chacha20-Poly1305 Authenticated Encryption with Associated Data (AEAD) construction specified in [RFC 8439].
-The library includes three implementations of this construction, all with the same API, for different platforms:
-
-* `Hacl_Chacha20Poly1305_32.h` contains the API for the portable C implementation that can be compiled and run on any platform that is 32-bit or higher.
-* `Hacl_Chacha20Poly1305_128.h` contains the API for the 128-bit vectorized C implementation that can be compiled and run on any platform that supports 128-bit SIMD instructions.
-* `Hacl_Chacha20Poly1305_256.h` contains the API for the 256-bit vectorized C implementation that can be compiled and run on any platform that supports 256-bit SIMD instructions.
-
+The library includes three implementations of this construction, all with the same API, for different platforms.
 All memory for the output variables have to be allocated by the caller.
 
 ## Available Implementations
@@ -18,6 +13,8 @@ All memory for the output variables have to be allocated by the caller.
 #include "Hacl_Chacha20Poly1305_32.h"
 ```
 
+A portable C implementation that can be compiled and run on any platform that is 32-bit or higher.
+
 This implementation works on all CPUs.
 ````
 
@@ -26,6 +23,8 @@ This implementation works on all CPUs.
 #include "Hacl_Chacha20Poly1305_128.h"
 ```
 
+A 128-bit vectorized C implementation that can be compiled and run on any platform that supports 128-bit SIMD instructions.
+
 Support for VEC128 is needed. Please see the [HACL Packages book].
 ````
 
@@ -34,11 +33,17 @@ Support for VEC128 is needed. Please see the [HACL Packages book].
 #include "Hacl_Chacha20Poly1305_256.h"
 ```
 
+A 256-bit vectorized C implementation that can be compiled and run on any platform that supports 256-bit SIMD instructions.
+
 Support for VEC256 is needed. Please see the [HACL Packages book].
 ````
 `````
 
-## Example
+## API Reference
+
+`````{tabs}
+````{group-tab} 32
+**Example**
 
 ```{literalinclude} ../../../../tests/chacha20poly1305.cc
 :language: C
@@ -47,55 +52,30 @@ Support for VEC256 is needed. Please see the [HACL Packages book].
 :end-before: "// END OneShot"
 ```
 
-## API Reference
-
-`````{tabs}
-
-````{group-tab} 32
-
 ```{doxygenfunction} Hacl_Chacha20Poly1305_32_aead_encrypt
 ```
-
-````
-
-````{group-tab} 128
-
-```{doxygenfunction} Hacl_Chacha20Poly1305_128_aead_encrypt
-```
-
-````
-
-````{group-tab} 256
-
-```{doxygenfunction} Hacl_Chacha20Poly1305_256_aead_encrypt
-```
-
-````
-`````
-
--------------------------------------------------------------------------------
-
-`````{tabs}
-
-````{group-tab} 32
-
 ```{doxygenfunction} Hacl_Chacha20Poly1305_32_aead_decrypt
 ```
-
 ````
-
 ````{group-tab} 128
+**Example**
 
+There is no example for now.
+
+```{doxygenfunction} Hacl_Chacha20Poly1305_128_aead_encrypt
+```
 ```{doxygenfunction} Hacl_Chacha20Poly1305_128_aead_decrypt
 ```
-
 ````
-
 ````{group-tab} 256
+**Example**
+
+There is no example for now.
 
+```{doxygenfunction} Hacl_Chacha20Poly1305_256_aead_encrypt
+```
 ```{doxygenfunction} Hacl_Chacha20Poly1305_256_aead_decrypt
 ```
-
 ````
 `````
 

docs/reference/hacl/dh/ec/curve25519.md

@@ -2,34 +2,34 @@
 
 Elliptic-curve Diffie-Hellman key agreement on Curve25519.
 
-## Implementations
-
-There are multiple implementations, i.e., ...
-
-* a portable implementation (`Hacl_Curve25519_51.h`),
-* a fast 64-bit implementation that requires BMI2 & ADX CPU support (`Hacl_Curve25519_64.h`), and
-* a slower 64-bit implementation without the requirements stated above (`Hacl_Curve25519_64_Slow.h`).
-
-## API Reference
+## Available Implementations
 
 `````{tabs}
 ````{group-tab} 51
 ```C
 #include "Hacl_Curve25519_51.h"
 ```
+
+A portable implementation.
 ````
 ````{group-tab} 64
 ```C
 #include "Hacl_Curve25519_64.h"
 ```
+
+A fast 64-bit implementation that requires BMI2 & ADX CPU support.
 ````
 ````{group-tab} 64 (Slow)
 ```C
 #include "Hacl_Curve25519_64_Slow.h"
 ```
+
+A slow 64-bit implementation without the requirements stated above.
 ````
 `````
 
+## API Reference
+
 `````{tabs}
 ````{group-tab} 51
 ```{doxygenfunction} Hacl_Curve25519_51_scalarmult

docs/reference/hacl/hash/blake2/blake2b.md

@@ -3,10 +3,29 @@
 BLAKE2b is optimized for 64-bit platforms and produces digests of any size between 1 and 64 bytes.
 It also has a build-in keying mechanism so that it can be used to replace HMAC-based constructions.
 
-## Example
+## API Reference
+
+### One-Shot
+
+**Available Implementations**
+
+`````{tabs}
+````{group-tab} 32
+```C
+#include "Hacl_Hash_Blake2.h"
+```
+````
+````{group-tab} 256
+```C
+#include "Hacl_Hash_Blake2b_256.h"
+```
+````
+`````
 
-The following example shows how to use the one-shot API with the base implementation (32) of BLAKE2b.
+**Example**
 
+`````{tabs}
+````{group-tab} 32
 ```{literalinclude} ../../../../../tests/blake2b.cc
 :language: C
 :dedent:
@@ -27,31 +46,26 @@ The following example shows how to use the one-shot API with the base implementa
 :start-after: "// ANCHOR(example)"
 :end-before: "// ANCHOR_END(example)"
 ```
-
-## API Reference
-
-### One-Shot
+````
+````{group-tab} 256
+There is no example for now.
+````
+`````
 
 `````{tabs}
 ````{group-tab} 32
-```C
-#include "Hacl_Hash_Blake2.h"
-```
-
 ```{doxygenfunction} Hacl_Blake2b_32_blake2b
 ```
 ````
 ````{group-tab} 256
-```C
-#include "Hacl_Hash_Blake2b_256.h"
-```
 ```{doxygenfunction} Hacl_Blake2b_256_blake2b
 ```
 ````
 `````
 
 ### Streaming (without key)
 
+**Available Implementations**
 
 `````{tabs}
 ````{group-tab} 32
@@ -66,69 +80,44 @@ The following example shows how to use the one-shot API with the base implementa
 ````
 `````
 
+**Example**
+
 `````{tabs}
 ````{group-tab} 32
-```{doxygentypedef} Hacl_Streaming_Blake2_blake2b_32_state
-```
+There is no example for now.
 ````
 ````{group-tab} 256
-```{doxygentypedef} Hacl_Streaming_Blake2b_256_blake2b_256_state
-```
+There is no example for now.
 ````
 `````
 
 `````{tabs}
 ````{group-tab} 32
-```{doxygenfunction} Hacl_Streaming_Blake2_blake2b_32_no_key_create_in
+```{doxygentypedef} Hacl_Streaming_Blake2_blake2b_32_state
 ```
-````
-````{group-tab} 256
-```{doxygenfunction} Hacl_Streaming_Blake2b_256_blake2b_256_no_key_create_in
+```{doxygenfunction} Hacl_Streaming_Blake2_blake2b_32_no_key_create_in
 ```
-````
-`````
-
-`````{tabs}
-````{group-tab} 32
 ```{doxygenfunction} Hacl_Streaming_Blake2_blake2b_32_no_key_init
 ```
-````
-````{group-tab} 256
-```{doxygenfunction} Hacl_Streaming_Blake2b_256_blake2b_256_no_key_init
-```
-````
-`````
-
-`````{tabs}
-````{group-tab} 32
 ```{doxygenfunction} Hacl_Streaming_Blake2_blake2b_32_no_key_update
 ```
-````
-````{group-tab} 256
-```{doxygenfunction} Hacl_Streaming_Blake2b_256_blake2b_256_no_key_update
-```
-````
-`````
-
-`````{tabs}
-````{group-tab} 32
 ```{doxygenfunction} Hacl_Streaming_Blake2_blake2b_32_no_key_finish
 ```
-````
-````{group-tab} 256
-```{doxygenfunction} Hacl_Streaming_Blake2b_256_blake2b_256_no_key_finish
-```
-````
-`````
-
-`````{tabs}
-````{group-tab} 32
 ```{doxygenfunction} Hacl_Streaming_Blake2_blake2b_32_no_key_free
 ```
 ````
 ````{group-tab} 256
+```{doxygentypedef} Hacl_Streaming_Blake2b_256_blake2b_256_state
+```
+```{doxygenfunction} Hacl_Streaming_Blake2b_256_blake2b_256_no_key_create_in
+```
+```{doxygenfunction} Hacl_Streaming_Blake2b_256_blake2b_256_no_key_init
+```
+```{doxygenfunction} Hacl_Streaming_Blake2b_256_blake2b_256_no_key_update
+```
+```{doxygenfunction} Hacl_Streaming_Blake2b_256_blake2b_256_no_key_finish
+```
 ```{doxygenfunction} Hacl_Streaming_Blake2b_256_blake2b_256_no_key_free
 ```
 ````
 `````
-