From 6f84c8807bb489b21b6ff40999444cb708b98d2f Mon Sep 17 00:00:00 2001
From: yangjie01 <yangjie01@baidu.com>
Date: Sat, 29 Aug 2026 18:56:39 +0800
Subject: [PATCH] docs(linalg): document the SIMD slice conversion panics

---
 rust/lance-linalg/src/distance/hamming.rs |  2 +-
 rust/lance-linalg/src/simd/f32.rs         | 10 ++++++++++
 rust/lance-linalg/src/simd/f64.rs         | 10 ++++++++++
 rust/lance-linalg/src/simd/i32.rs         |  5 +++++
 rust/lance-linalg/src/simd/u8.rs          |  5 +++++
 5 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/rust/lance-linalg/src/distance/hamming.rs b/rust/lance-linalg/src/distance/hamming.rs
index b1a52cd7fbe..5436e97b8c5 100644
--- a/rust/lance-linalg/src/distance/hamming.rs
+++ b/rust/lance-linalg/src/distance/hamming.rs
@@ -512,7 +512,7 @@ unsafe fn hamming_batch_avx512(query: u64, targets: &[u64], results: &mut [u32])
     }
 }
 
-/// AVX2 popcount using lookup table (Harley-Seal / PSHUFB method).
+/// AVX2 popcount via a PSHUFB nibble-lookup table.
 ///
 /// The chunk loop reaches only the first `targets.len() / 4 * 4` slots through a
 /// raw pointer, 4 x u32 per chunk with no bounds check; the trailing slots go
diff --git a/rust/lance-linalg/src/simd/f32.rs b/rust/lance-linalg/src/simd/f32.rs
index 434a1ef9f18..85675610f59 100644
--- a/rust/lance-linalg/src/simd/f32.rs
+++ b/rust/lance-linalg/src/simd/f32.rs
@@ -147,6 +147,11 @@ fn gather_scalar_x86(slice: &[f32], indices: &[i32; 8]) -> f32x8 {
 }
 
 impl From<&[f32]> for f32x8 {
+    /// Loads the first 8 elements of `value`.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `value` has fewer than 8 elements.
     fn from(value: &[f32]) -> Self {
         assert!(
             value.len() >= 8,
@@ -532,6 +537,11 @@ impl std::fmt::Debug for f32x16 {
 }
 
 impl From<&[f32]> for f32x16 {
+    /// Loads the first 16 elements of `value`.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `value` has fewer than 16 elements.
     fn from(value: &[f32]) -> Self {
         assert!(
             value.len() >= 16,
diff --git a/rust/lance-linalg/src/simd/f64.rs b/rust/lance-linalg/src/simd/f64.rs
index 129b2f088ec..65ba9658be4 100644
--- a/rust/lance-linalg/src/simd/f64.rs
+++ b/rust/lance-linalg/src/simd/f64.rs
@@ -44,6 +44,11 @@ impl std::fmt::Debug for f64x4 {
 }
 
 impl From<&[f64]> for f64x4 {
+    /// Loads the first 4 elements of `value`.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `value` has fewer than 4 elements.
     fn from(value: &[f64]) -> Self {
         assert!(
             value.len() >= 4,
@@ -393,6 +398,11 @@ impl std::fmt::Debug for f64x8 {
 }
 
 impl From<&[f64]> for f64x8 {
+    /// Loads the first 8 elements of `value`.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `value` has fewer than 8 elements.
     fn from(value: &[f64]) -> Self {
         assert!(
             value.len() >= 8,
diff --git a/rust/lance-linalg/src/simd/i32.rs b/rust/lance-linalg/src/simd/i32.rs
index 6e0812928db..6748c67569e 100644
--- a/rust/lance-linalg/src/simd/i32.rs
+++ b/rust/lance-linalg/src/simd/i32.rs
@@ -49,6 +49,11 @@ impl std::fmt::Debug for i32x8 {
 }
 
 impl From<&[i32]> for i32x8 {
+    /// Loads the first 8 elements of `value`.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `value` has fewer than 8 elements.
     fn from(value: &[i32]) -> Self {
         assert!(
             value.len() >= 8,
diff --git a/rust/lance-linalg/src/simd/u8.rs b/rust/lance-linalg/src/simd/u8.rs
index 8720cd86e8c..756406ea035 100644
--- a/rust/lance-linalg/src/simd/u8.rs
+++ b/rust/lance-linalg/src/simd/u8.rs
@@ -84,6 +84,11 @@ impl std::fmt::Debug for u8x16 {
 }
 
 impl From<&[u8]> for u8x16 {
+    /// Loads the first 16 elements of `value`.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `value` has fewer than 16 elements.
     fn from(value: &[u8]) -> Self {
         assert!(
             value.len() >= 16,