From 4322e30dd71657e511564131596a7479eac676b3 Mon Sep 17 00:00:00 2001
From: therewillbecode <tomw08@gmail.com>
Date: Mon, 10 Mar 2025 09:05:52 +0000
Subject: [PATCH] Improve docs for eslint rule guard-for-in

---
 .../src/rules/eslint/guard_for_in.rs          | 36 +++++++++++++++++--
 1 file changed, 34 insertions(+), 2 deletions(-)

diff --git a/crates/oxc_linter/src/rules/eslint/guard_for_in.rs b/crates/oxc_linter/src/rules/eslint/guard_for_in.rs
index 43efbbee07dde..896054eb7fcf3 100644
--- a/crates/oxc_linter/src/rules/eslint/guard_for_in.rs
+++ b/crates/oxc_linter/src/rules/eslint/guard_for_in.rs
@@ -16,15 +16,47 @@ pub struct GuardForIn;
 
 declare_oxc_lint!(
     /// ### What it does
-    /// This rule is aimed at preventing unexpected behavior that could arise from using a for in loop without filtering the results in the loop. As such, it will warn when for in loops do not filter their results with an if statement.
+    ///
+    /// Require for-in loops to include an if statement.
     ///
     /// ### Why is this bad?
     ///
+    /// Looping over objects with a `for in` loop will include properties that are inherited through
+    /// the prototype chain. Using a `for in` loop without filtering the results in the loop can
+    /// lead to unexpected items in your for loop which can then lead to unexpected behaviour.
+    ///
+    /// ### Examples
+    ///
+    /// Examples of **incorrect** code for this rule:
+    ///
+    /// ```javascript
+    /// for (key in foo) {
+    ///   doSomething(key);
+    /// }
+    /// ```
     ///
-    /// ### Example
+    /// Examples of **correct** code for this rule:
     /// ```javascript
     /// for (key in foo) {
+    ///   if (Object.hasOwn(foo, key)) {
     ///     doSomething(key);
+    ///   }
+    /// }
+    /// ```
+    ///
+    /// ```javascript
+    /// for (key in foo) {
+    ///   if (Object.prototype.hasOwnProperty.call(foo, key)) {
+    ///     doSomething(key);
+    ///   }
+    /// }
+    /// ```
+    ///
+    /// ```javascript
+    /// for (key in foo) {
+    ///    if ({}.hasOwnProperty.call(foo, key)) {
+    ///        doSomething(key);
+    ///    }
     /// }
     /// ```
     GuardForIn,