From 3067e60e401e5a3b567bcfb223c8290ee87a1639 Mon Sep 17 00:00:00 2001
From: "Garth N. Wells" <gnw20@cam.ac.uk>
Date: Sat, 16 Nov 2024 22:04:28 +0000
Subject: [PATCH] Doc fix

---
 cpp/basix/precompute.h | 46 ++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 44 insertions(+), 2 deletions(-)

diff --git a/cpp/basix/precompute.h b/cpp/basix/precompute.h
index 71f26b9f7..744a44575 100644
--- a/cpp/basix/precompute.h
+++ b/cpp/basix/precompute.h
@@ -39,7 +39,48 @@ using scalar_value_type_t = typename scalar_value_type<T>::value_type;
 
 /// @brief Prepare a permutation.
 ///
-/// @param[in,out] perm A permutation
+/// Computes  representation of the permutation that allows the
+/// permutation to be applied without any temporary memory assignment.
+/// In pseudo code, this function does the following:
+///
+/// \code{.pseudo}
+/// FOR index, entry IN perm:
+///     new_index = entry
+///     WHILE new_index < index:
+///         new_index = perm[new_index]
+///     OUT[index] = new_index
+/// \endcode
+///
+/// Example
+/// -------
+/// Consider the permutation `P = [1, 4, 0, 5, 2, 3]`.
+///
+/// -# First, we look at the 0th entry. `P[0]` is 1. This is greater
+/// than 0, so the 0th entry of the output is 1.
+///
+/// -# Next, we look at the 1st entry. `P[1]` is 4. This is greater than
+///   1, so the 1st entry of the output is 4.
+/// -# Next, we look at the 2nd entry. `P[2]` is 0. This is less than 2,
+///   so we look at `P[0]`. `P[0]` is 1. This is less than 2, so we look at
+///   `P[1]`. `P[1]` is 4. This is greater than 2, so the 2nd entry of the
+///   output is 4.
+/// -# Next, we look at the 3rd entry. `P[3]` is 5. This is greater than 3,
+///   so the 3rd entry of the output is 5.
+/// -# Next, we look at the 4th entry. `P[4]` is 2. This is less than 4, so
+///   we look at `P[2]`. `P[2]` is 0. This is less than 4, so we look at
+///  `P[0]`. `P[0]` is 1. This is less than 4, so we look at `P[1]`.
+///  `P[1]` is 4. This is greater than (or equal to) 4, so the 4th entry
+///  of the output is 4.
+/// -# Next, we look at the 5th entry. `P[5]` is 3. This is less than 5,
+///   so we look at `P[3]`. `P[3]` is 5. This is greater than (or equal
+///   to) 5, so the 5th entry of the output is 5.
+///
+/// Hence, the output of this function in this case is `[1, 4, 4, 5, 4, 5]`.
+///
+/// For an example of how the permutation in this form is applied, see
+/// apply_permutation().
+///
+/// @param[in,out] perm A permutation.
 void prepare_permutation(std::span<std::size_t> perm);
 
 /// @brief Apply a (precomputed) permutation \f$v = P u\f$.
@@ -65,7 +106,8 @@ void prepare_permutation(std::span<std::size_t> perm);
 /// this example, we look at how this representation can be used to
 /// apply this permutation to the array `A = [a, b, c, d, e, f]`.
 ///
-/// - `P2[0]` is 1, so we swap `A[0]` and `A[1]`. After this, `A = [b,a, c, d, e, f]`.
+/// - `P2[0]` is 1, so we swap `A[0]` and `A[1]`. After this,
+///   `A = [b, a, c, d, e, f]`.
 ///
 /// - `P2[1]` is 4, so we swap `A[1]` and `A[4]`. After this, `A = [b, e, c, d, a, f]`.
 ///