From d009a44975bbe4e6995c7c478486da55784bc30d Mon Sep 17 00:00:00 2001
From: David Wood <david.wood2@arm.com>
Date: Fri, 8 May 2026 12:54:38 +0000
Subject: [PATCH] intrinsic-test: document `iter_specializations`

It isn't necessarily obvious what this function does
---
 .../crates/intrinsic-test/src/common/constraint.rs    |  6 +++---
 .../crates/intrinsic-test/src/common/intrinsic.rs     | 11 +++++++++++
 2 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/library/stdarch/crates/intrinsic-test/src/common/constraint.rs b/library/stdarch/crates/intrinsic-test/src/common/constraint.rs
index 5984e0fcc22f..c78eb3541cfd 100644
--- a/library/stdarch/crates/intrinsic-test/src/common/constraint.rs
+++ b/library/stdarch/crates/intrinsic-test/src/common/constraint.rs
@@ -1,10 +1,10 @@
 use serde::Deserialize;
 use std::ops::Range;
 
-/// Describes the values to test for a const generic parameter.
+/// Describes the values to test for a const generic parameter
 #[derive(Debug, PartialEq, Clone, Deserialize)]
 pub enum Constraint {
-    /// Test a single value.
+    /// Test a single value
     Equal(i64),
     /// Test a range of values, e.g. `0..16`.
     Range(Range<i64>),
@@ -13,7 +13,7 @@ pub enum Constraint {
 }
 
 impl Constraint {
-    /// Iterate over the values of this constraint.
+    /// Returns an iterator over the values of this constraint
     pub fn iter<'a>(&'a self) -> impl Iterator<Item = i64> + 'a {
         match self {
             Constraint::Equal(i) => std::slice::Iter::default().copied().chain(*i..*i + 1),
diff --git a/library/stdarch/crates/intrinsic-test/src/common/intrinsic.rs b/library/stdarch/crates/intrinsic-test/src/common/intrinsic.rs
index 76e5959153d0..d69644388a83 100644
--- a/library/stdarch/crates/intrinsic-test/src/common/intrinsic.rs
+++ b/library/stdarch/crates/intrinsic-test/src/common/intrinsic.rs
@@ -19,6 +19,10 @@ pub struct Intrinsic<T: IntrinsicTypeDefinition> {
     pub arch_tags: Vec<String>,
 }
 
+/// Invokes `f` for each combination of the values in the constraint ranges.
+///
+/// For example, given `constraints=[Equal(0), Range(1..2), Set([3, 4])]` and `imm_values=[]`, this
+/// produces the four calls to `f`: `f([0, 1, 3])`, `f([0, 1, 4])`, `f([0, 2, 3])`, `f([0, 2, 4])`.
 fn recurse_specializations<'a, E>(
     constraints: &mut (impl Iterator<Item = &'a Constraint> + Clone),
     imm_values: &mut Vec<i64>,
@@ -37,6 +41,13 @@ fn recurse_specializations<'a, E>(
 }
 
 impl<T: IntrinsicTypeDefinition> Intrinsic<T> {
+    /// Invokes `f` for "specialisation" of the intrinsic - a specific instantiation of the
+    /// constant generics of the intrinsic. `f` takes a slice where the `i`th element corresponds
+    /// to the value of the `i`th const generic argument of the intrinsic.
+    ///
+    /// For an intrinsic with three arguments with constraints `Equal(0)`, `Range(1..2)`,
+    /// `Set([3, 4])` respectively, this would produce four calls to `f`: `f(0, 1, 3)`,
+    /// `f(0, 1, 4)`, `f(0, 2, 3)`, `f(0, 2, 4)`.
     pub fn iter_specializations<E>(
         &self,
         mut f: impl FnMut(&[i64]) -> Result<(), E>,