intrinsic-test: document iter_specializations

It isn't necessarily obvious what this function does

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),

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>,