Correct documentation of integer_division_remainder_used

clippy_lints/src/integer_division_remainder_used.rs

@@ -12,16 +12,31 @@ declare_clippy_lint! {
     ///
     /// ### Why restrict this?
     /// In cryptographic contexts, division can result in timing sidechannel vulnerabilities,
-    /// and needs to be replaced with constant-time code instead (e.g. Barrett reduction).
+    /// and needs to be replaced with constant-time code instead.
+    ///
+    /// If within its capabilities, the compiler will [optimize away any constant-time implementation](https://eprint.iacr.org/2025/435)
+    /// of an algorithm. This can and does lead to unexpected non-constant execution times outside of
+    /// the user's agency.
+    ///
+    /// The solution to achieve constant-time operation is often to either implement
+    /// a constant-time algorithm in assembly code, or to delegate such operations to a well-known,
+    /// audited and / or certified cryptographic library.
     ///
     /// ### Example
     /// ```no_run
-    /// let my_div = 10 / 2;
-    /// ```
-    /// Use instead:
-    /// ```no_run
-    /// let my_div = 10 >> 1;
+    /// let _ = 10 / 2; // This will run faster because it's a division by a multiple of 2.
+    /// let _ = 10 / 3; // This will run slower than the above.
     /// ```
+    ///
+    /// ### Final Notes
+    ///
+    /// This lint was motivated by the [KyberSlash](https://kyberslash.cr.yp.to/) attack. Be safe out there.
+    ///
+    /// For more information regarding this lint and on how to mitigate division-based timing attacks,
+    /// please check the [last conversation concerning this lint](https://github.com/rust-lang/rust-clippy/pull/15661#issuecomment-3289549360).
+    ///
+    /// This documentation was last updated on September 2025. Bear this in mind if you read this in the
+    /// future, and double-check that this lint is up-to-date for your current security needs.
     #[clippy::version = "1.79.0"]
     pub INTEGER_DIVISION_REMAINDER_USED,
     restriction,